@gjsify/cli 0.64.3-next.262 → 0.64.5

package/lib/commands/publish.d.ts

@@ -5,6 +5,7 @@ import { type WorkspacePin } from '../utils/publish-pins.js';
 import { type HoldReason } from '../utils/publish-hold.js';
 import { type Classification } from '../utils/publish-status.js';
 import { OtpProvider } from '../utils/npm-otp.js';
+import { type TransientRetryOptions } from '../utils/transient-retry.js';
 interface PublishOptions {
     path?: string;
     tag?: string;
@@ -16,6 +17,10 @@ interface PublishOptions {
     'verify-defer'?: boolean;
     'hold-timeout'?: number;
     'report-ledger'?: boolean;
+    'fail-on-unsettled'?: boolean;
+    'held-names'?: boolean;
+    'settle-ledger'?: boolean;
+    'settle-timeout'?: number;
     ref?: string;
     provenance?: boolean;
     'dry-run'?: boolean;
@@ -24,6 +29,12 @@ interface PublishOptions {
     'check-trusted'?: boolean;
 }
 export declare const publishCommand: Command<unknown, PublishOptions>;
+/**
+ * Whether a 409 / 403 "previously published" answer counts as success. `--tolerate-republish`
+ * says yes; so does a PUT that was retried after a 5xx, since the first attempt may have landed
+ * and the retry then finds its own version.
+ */
+export declare function acceptsRepublish(status: number, text: string, tolerate: boolean, retriedPut: boolean): boolean;
 /** Input to {@link publishWorkspace} — the token-auth-aware, OTP-shareable publish flow. */
 export interface PublishWorkspaceInput {
     /** Workspace directory to pack + publish. */
@@ -70,6 +81,8 @@ export interface PublishWorkspaceInput {
      * holding this package. Default {@link DEFAULT_HOLD_WAIT_MS}.
      */
     holdWaitMs?: number;
+    /** Retry policy for 5xx/429/network errors on the PUT. Tests pass `{ baseMs: 0 }`. */
+    putRetry?: TransientRetryOptions;
 }
 /** Discriminated result of {@link publishWorkspace}; the caller owns presentation. */
 export type PublishOutcome = {

package/lib/commands/publish.js

@@ -50,11 +50,12 @@ import { getNpmTrustedToken, hasGithubOidcEnv, OidcExchangeError, OidcUnavailabl
 import { diagnose404, is404DiagnosticCandidate } from '../utils/publish-diagnose.js';
 import { DEFAULT_VERIFY_BUDGET_MS, formatUnconfirmedPublish, probePackageName, verifyPublishedVersion, } from '../utils/publish-readback.js';
 import { collectWorkspacePins, REQUIRED_BLOCK } from '../utils/publish-pins.js';
-import { appendLedger, DEFAULT_HOLD_WAIT_MS, findUnavailablePins, holdsPublish, readLedger, recordUnserved, renderLedgerSummary, summariseReasons, } from '../utils/publish-hold.js';
+import { appendLedger, DEFAULT_HOLD_WAIT_MS, findUnavailablePins, holdsPublish, markHeldPublished, pendingEntries, readLedger, recordUnserved, renderLedgerSummary, settleUnserved, summariseReasons, } from '../utils/publish-hold.js';
 import { describeClass, statusTokenFromEnv } from '../utils/publish-status.js';
 import { loadNpmrc } from '../utils/load-npmrc.js';
 import { OtpProvider, withOtpRetry, isOtpChallenge } from '../utils/npm-otp.js';
 import { promptLine } from '../utils/prompt.js';
+import { fetchWithTransientRetry } from '../utils/transient-retry.js';
 export const publishCommand = {
     command: 'publish [path]',
     description: 'Pack + upload the workspace at <path> (default: cwd) to its npm registry. Drop-in for `npm publish` with workspace:^ rewrite handled automatically.',
@@ -102,6 +103,26 @@ export const publishCommand = {
         description: 'Print the job-summary markdown for the publish ledger named by $GJSIFY_PUBLISH_LEDGER (versions npm accepted but does not serve, packages held because of them, the recovery command) and exit. Pair with `--ref <tag>`.',
         type: 'boolean',
         default: false,
+    })
+        .option('fail-on-unsettled', {
+        description: 'With --report-ledger: exit 1 when any package is still HELD or any accepted version is still unserved, naming them and the recovery command. The end-of-sweep gate: a sweep that left something behind must be red, not a warning.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('held-names', {
+        description: 'Print, one per line, the packages the ledger shows HELD and not yet published, and exit. Feeds the held-package second pass (.github/scripts/retry-held-publish.sh).',
+        type: 'boolean',
+        default: false,
+    })
+        .option('settle-ledger', {
+        description: 'Wait up to --settle-timeout for every version the ledger records as accepted-but-unserved to be served (the longer read-back the sweep defers), record each as served, and exit.',
+        type: 'boolean',
+        default: false,
+    })
+        .option('settle-timeout', {
+        description: 'With --settle-ledger: seconds to wait. Versions poll concurrently, so this is the longest lag tolerated, not a sum. Default 600 (the fatal read-back default; measured lags reach 368 s).',
+        type: 'number',
+        default: DEFAULT_VERIFY_BUDGET_MS / 1000,
     })
         .option('ref', {
         description: 'With --report-ledger: the git ref to put in the printed recovery command.',
@@ -158,10 +179,45 @@ export const publishCommand = {
         const checkTrustedOnly = args['check-trusted'] === true;
         const trustedFlag = args.trusted;
         const verbose = Boolean(process.env.GJSIFY_PUBLISH_DEBUG);
+        const ledgerPath = process.env.GJSIFY_PUBLISH_LEDGER;
+        if (args['held-names'] === true) {
+            for (const e of pendingEntries(readLedger(ledgerPath)).held)
+                process.stdout.write(`${e.name}\n`);
+            return;
+        }
+        if (args['settle-ledger'] === true) {
+            const settleSeconds = args['settle-timeout'] ?? DEFAULT_VERIFY_BUDGET_MS / 1000;
+            if (!Number.isFinite(settleSeconds) || settleSeconds < 0) {
+                console.error(`gjsify publish: --settle-timeout must be a non-negative number of seconds, got ${JSON.stringify(args['settle-timeout'])}`);
+                return process.exit(2);
+            }
+            const npmrc = await loadNpmrc(process.cwd());
+            const served = await settleUnserved({
+                entries: readLedger(ledgerPath),
+                ledgerPath,
+                registryFor: (name) => (process.env.npm_config_registry ?? registryFor(name, npmrc) ?? DEFAULT_REGISTRY).replace(/\/$/, ''),
+                budgetMs: Math.max(1, Math.round(settleSeconds * 1000)),
+                log: verbose ? (m) => console.error(m) : undefined,
+            });
+            for (const key of served)
+                process.stdout.write(`served after settling: ${key}\n`);
+            return;
+        }
         if (args['report-ledger'] === true) {
-            const summary = renderLedgerSummary(readLedger(process.env.GJSIFY_PUBLISH_LEDGER), args.ref ?? '<tag>');
+            const entries = readLedger(ledgerPath);
+            const summary = renderLedgerSummary(entries, args.ref ?? '<tag>');
             if (summary)
                 process.stdout.write(`${summary}\n`);
+            if (args['fail-on-unsettled'] === true) {
+                const { unserved, held } = pendingEntries(entries);
+                const names = [...new Set([...held, ...unserved].map((e) => e.name))];
+                if (names.length > 0) {
+                    const ref = args.ref ?? '<tag>';
+                    console.error(`gjsify publish: ${held.length} package(s) still HELD and ${unserved.length} version(s) still unserved after the second pass: ${names.join(' ')}\n` +
+                        `  recover: re-run THIS run (\`gh run rerun <run-id>\` — keeps the version; never a new dispatch on the next channel, which mints a new one), or for a release: gh workflow run release.yml --ref ${ref} -f skip_publish=false -f only='${names.join(' ')}'`);
+                    return process.exit(1);
+                }
+            }
             return;
         }
         const holdSeconds = args['hold-timeout'] ?? DEFAULT_HOLD_WAIT_MS / 1000;
@@ -277,11 +333,29 @@ export const publishCommand = {
             otpProvider,
             seedOtpFirst: otp !== undefined,
             verifyBudgetMs,
-            holdWaitMs: Math.round(holdSeconds * 1000),
+            holdWaitMs: Math.min(Math.round(holdSeconds * 1000), remainingHoldDeadlineMs()),
         });
         reportPublishOutcome(outcome, args.json === true, deferUnconfirmed);
     },
 };
+/**
+ * Milliseconds left until `GJSIFY_HOLD_DEADLINE` (epoch ms), or Infinity when unset. The
+ * held-package second pass is one `gjsify publish` PROCESS per package, so each would otherwise
+ * pay the full `--hold-timeout` on the same blocker; a shared deadline bounds the whole pass.
+ */
+function remainingHoldDeadlineMs() {
+    const until = Number(process.env.GJSIFY_HOLD_DEADLINE);
+    return Number.isFinite(until) && until > 0 ? Math.max(0, until - Date.now()) : Infinity;
+}
+/**
+ * Whether a 409 / 403 "previously published" answer counts as success. `--tolerate-republish`
+ * says yes; so does a PUT that was retried after a 5xx, since the first attempt may have landed
+ * and the retry then finds its own version.
+ */
+export function acceptsRepublish(status, text, tolerate, retriedPut) {
+    const conflict = status === 409 || (status === 403 && /previously published/i.test(text));
+    return conflict && (tolerate || retriedPut);
+}
 /**
  * Pack + PUT a single workspace to its npm registry, returning a structured
  * outcome instead of writing/exiting. Extracted from the `publish` command so
@@ -465,13 +539,24 @@ export async function publishWorkspace(input) {
     const bodyStr = JSON.stringify(payload);
     // Each attempt clones the base headers and adds `npm-otp` (+ legacy
     // auth-type, matching buildPublishHeaders) when a code is supplied.
-    const doPut = (code) => {
+    //
+    // A transient 5xx/429/network error is retried here, inside the OTP loop (a 401 challenge is
+    // not transient and passes straight through). The first attempt may have LANDED despite its
+    // 5xx, so `retriedPut` makes a later 409 / "previously published" count as success below.
+    let retriedPut = false;
+    const doPut = async (code) => {
         const reqHeaders = { ...headers };
         if (code) {
             reqHeaders['npm-otp'] = code;
             reqHeaders['npm-auth-type'] = 'legacy';
         }
-        return fetch(url, { method: 'PUT', headers: reqHeaders, body: bodyStr });
+        const { response, retried } = await fetchWithTransientRetry(() => fetch(url, { method: 'PUT', headers: reqHeaders, body: bodyStr }), {
+            log: (m) => console.error(`gjsify publish: PUT ${packed.name}@${packed.version}: ${m}`),
+            ...input.putRetry,
+        });
+        if (retried > 0)
+            retriedPut = true;
+        return response;
     };
     const res = await withOtpRetry(doPut, otpProvider, { seedFirstAttempt: input.seedOtpFirst });
     if (verbose) {
@@ -604,6 +689,7 @@ export async function publishWorkspace(input) {
                 }),
             };
         }
+        markHeldPublished(ledgerPath, packed.name, packed.version);
         return {
             ok: true,
             action: 'published',
@@ -633,8 +719,7 @@ export async function publishWorkspace(input) {
     // this is the path a `publish-unconfirmed` re-run always lands on: exempting
     // it would leave the documented remediation reporting a success nothing
     // checked. Cost is one GET, on a path that only runs on a re-publish.
-    const isRepublishConflict = res.status === 409 || (res.status === 403 && /previously published/i.test(text));
-    if (isRepublishConflict && tolerate) {
+    if (acceptsRepublish(res.status, text, tolerate, retriedPut)) {
         const readback = await readBack();
         if (readback && !readback.confirmed) {
             return {
@@ -659,6 +744,7 @@ export async function publishWorkspace(input) {
                 }),
             };
         }
+        markHeldPublished(ledgerPath, packed.name, packed.version);
         return {
             ok: true,
             action: 'republish-tolerated',

package/lib/commands/ship.js

@@ -26,12 +26,16 @@ import { CHANNELS, CHANNEL_ENV, parseDeclaredChannel } from '../utils/channel.js
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { Config } from '../config.js';
+import { ensurePkgDir } from './dlx.js';
 import { renderDesktopEntry, renderMetainfoApp, renderMetainfoCli, validateAppMetadata, } from '../utils/app-metadata.js';
 import { readPackageJson } from '../utils/pkg-json.js';
+import { parseSpec } from '../utils/parse-spec.js';
+import { cliVersion } from '../utils/publish-headers.js';
 import { describeExit, spawnToCompletion } from '../utils/spawn.js';
 import { buildDeb } from '../utils/ship/deb.js';
 import { deriveDepends, warnAboutGjsFloor, warnAboutNodeFloor } from '../utils/ship/depends.js';
 import { isGtkRuntimeTarget, stageAppRuntime } from '../utils/ship/app-runtime.js';
+import { acquireGtkRuntime } from '../utils/ship/gtk-runtime-acquire.js';
 import { discoverPayload } from '../utils/ship/discover.js';
 import { appDirFor, appDirPayload, appImageHostRequirements, appImageRuntimeNotice, buildAppImage, findPinnedRuntime, stampAppDirTimes, } from '../utils/ship/appimage.js';
 import { buildDmgImage, dmgVolumeDir, dmgVolumeName } from '../utils/ship/dmg.js';
@@ -411,7 +415,7 @@ async function assemble(args) {
     // `.deb`/`.rpm` `Depends:` is the promise that `node` or `gjs` is on `PATH`, and
     // carrying a second copy inside the payload would be a private interpreter no
     // distribution update ever patches.
-    const runtime = resolveCarriedRuntime(layout, settings, projectDir);
+    const runtime = await resolveCarriedRuntime(layout, settings, projectDir);
     const stageInputs = {
         bundleFiles: discovered.bundleFiles,
         launcher: renderLauncher(settings, basename(settings.bundlePath), layout, runtime.launcher),
@@ -761,21 +765,35 @@ function announceSigning(sign, notarize) {
  * thing to make non-vacuous on this layout, since a JavaScript bundle has no
  * cputype to disagree with.
  */
-function resolveCarriedRuntime(layout, settings, projectDir) {
+async function resolveCarriedRuntime(layout, settings, projectDir) {
     const empty = { files: [], launcher: {}, found: [], missing: [] };
     if (layout.os === 'linux' || settings.app !== 'node')
         return empty;
     const target = `${layout.os}-${settings.arch}`;
     if (!isGtkRuntimeTarget(target))
         return empty;
+    // The closure is fetched, not installed: a project that lists it puts a second
+    // GLib next to Homebrew's in its dev tree (see `gtk-runtime-acquire.ts`).
+    const acquired = await acquireGtkRuntime({
+        target,
+        version: cliVersion(),
+        discovery: { cwd: projectDir },
+        ensure: async (spec) => (await ensurePkgDir(parseSpec(spec), { verbose: false, cacheMaxAge: DLX_CACHE_MAX_AGE_MIN, frozen: false }))
+            .pkgDir,
+        log: (message) => console.log(`${LOG} ${message}`),
+    });
     return stageAppRuntime({
         layout,
         identity: settings,
         target,
         cwd: projectDir,
         interpreter: isNodeRuntimeTarget(target) ? resolveNodeRuntime(target, { cwd: projectDir }) : null,
+        ...(acquired.kind === 'fetched' ? { fetchedGtkRuntimeDir: acquired.dir } : {}),
+        ...(acquired.kind === 'failed' ? { gtkFetchFailure: acquired.reason } : {}),
     });
 }
+/** How long a fetched runtime stays in the dlx cache — the same week `gjsify showcase` uses. */
+const DLX_CACHE_MAX_AGE_MIN = 60 * 24 * 7;
 /**
  * Phase two: pack a stage that was assembled somewhere else.
  *

package/lib/utils/npm-oidc.d.ts

@@ -14,7 +14,7 @@ interface OidcExchangeOptions {
      * `--tolerate-untrusted-new` and the misconfig hints still fire on the first response.
      */
     maxRetries?: number;
-    /** Base backoff in ms for transient retries; doubles each attempt (capped 8s). Default 1000. Tests pass 0. */
+    /** Base backoff in ms for transient retries; doubles each attempt (capped 30s, `Retry-After` honored). Default 1000. Tests pass 0. */
     retryBaseMs?: number;
 }
 export interface OidcExchangeResult {

package/lib/utils/npm-oidc.js

@@ -13,8 +13,7 @@
 //
 // Reference: refs/npm-cli/lib/utils/oidc.js
 // Original: Copyright (c) npm contributors. Artistic-2.0.
-/** HTTP statuses worth retrying — npm-side transient/overload conditions. */
-const TRANSIENT_EXCHANGE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+import { isTransientStatus, retryDelayMs } from './transient-retry.js';
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export class OidcUnavailableError extends Error {
     reason;
@@ -146,7 +145,7 @@ export async function exchangeOidcForNpmToken(args) {
         catch (netErr) {
             // Network-level failure (DNS, connection reset, TLS): transient.
             if (attempt < maxRetries) {
-                const delay = Math.min(retryBaseMs * 2 ** attempt, 8000);
+                const delay = retryDelayMs(attempt, retryBaseMs);
                 log?.(`gjsify oidc: network error for ${packageName} (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms`);
                 await sleep(delay);
                 continue;
@@ -156,8 +155,9 @@ export async function exchangeOidcForNpmToken(args) {
         const text = await res.text().catch(() => '');
         if (!res.ok) {
             // Only TRANSIENT npm-side failures retry — see `maxRetries`.
-            if (TRANSIENT_EXCHANGE_STATUSES.has(res.status) && attempt < maxRetries) {
-                const delay = Math.min(retryBaseMs * 2 ** attempt, 8000);
+            if (isTransientStatus(res.status) && attempt < maxRetries) {
+                // `Retry-After` wins over the backoff when npm sends one (429/503 during an incident).
+                const delay = retryDelayMs(attempt, retryBaseMs, res.headers.get('retry-after'));
                 log?.(`gjsify oidc: transient ${res.status} ${res.statusText} for ${packageName} (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms`);
                 await sleep(delay);
                 continue;

package/lib/utils/publish-hold.d.ts

@@ -27,7 +27,10 @@ export type LedgerEntry =
     version: string;
     reasons: HoldReason[];
 }
-/** A later probe found a version an earlier `unserved` entry recorded now served; it supersedes that entry. */
+/**
+ * The version is now served; it supersedes an earlier `unserved` OR `held` entry (last entry
+ * wins) — a later probe found it, or the held-package second pass published it.
+ */
  | {
     ev: 'served';
     name: string;
@@ -86,4 +89,41 @@ export declare function recordUnserved(input: {
  * and why, and the exact command that publishes the held set once their
  * dependencies are installable. `undefined` when nothing needs saying.
  */
+type UnservedEntry = Extract<LedgerEntry, {
+    ev: 'unserved';
+}>;
+type HeldEntry = Extract<LedgerEntry, {
+    ev: 'held';
+}>;
+/** One entry per `name@version` — the LAST one — keeping only those still not served. */
+export declare function pendingEntries(entries: readonly LedgerEntry[]): {
+    unserved: UnservedEntry[];
+    held: HeldEntry[];
+};
+/**
+ * Record that a package this run once HELD has now been published, so its dependents stop
+ * holding on it (`judgePin` reads the last entry) and the end-of-job check stops naming it.
+ */
+export declare function markHeldPublished(path: string | undefined, name: string, version: string): void;
+export interface SettleUnservedInput {
+    entries: readonly LedgerEntry[];
+    ledgerPath: string | undefined;
+    /** Registry for a package name (scoped registries differ). */
+    registryFor: (name: string) => string;
+    /** One shared deadline: the entries poll concurrently, so the cost is the longest lag, not the sum. */
+    budgetMs: number;
+    authorization?: string;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    log?: (msg: string) => void;
+}
+/**
+ * Wait for versions npm ACCEPTED but did not serve inside the sweep's 5 s read-back, and append
+ * `served` for each one that shows up. This is the longer read-back the sweep deliberately defers
+ * (publishing.md: lags reach 252–368 s). A TERMINAL class (blocked/deleted/staged/missing) is a
+ * spent number — waiting cannot help, so it is skipped. Returns the names confirmed.
+ */
+export declare function settleUnserved(input: SettleUnservedInput): Promise<string[]>;
 export declare function renderLedgerSummary(entries: readonly LedgerEntry[], ref: string): string | undefined;
+export {};

package/lib/utils/publish-hold.js

@@ -181,15 +181,55 @@ export async function recordUnserved(input) {
     });
     return classification;
 }
+/** One entry per `name@version` — the LAST one — keeping only those still not served. */
+export function pendingEntries(entries) {
+    const last = new Map();
+    for (const e of entries)
+        last.set(`${e.name}@${e.version}`, e);
+    const pending = [...last.values()];
+    return {
+        unserved: pending.filter((e) => e.ev === 'unserved'),
+        held: pending.filter((e) => e.ev === 'held'),
+    };
+}
 /**
- * The job-summary markdown for a ledger: what is unserved and why, what was held
- * and why, and the exact command that publishes the held set once their
- * dependencies are installable. `undefined` when nothing needs saying.
+ * Record that a package this run once HELD has now been published, so its dependents stop
+ * holding on it (`judgePin` reads the last entry) and the end-of-job check stops naming it.
  */
+export function markHeldPublished(path, name, version) {
+    const last = [...readLedger(path)].reverse().find((e) => e.name === name && e.version === version);
+    if (last?.ev === 'held')
+        appendLedger(path, { ev: 'served', name, version });
+}
+/**
+ * Wait for versions npm ACCEPTED but did not serve inside the sweep's 5 s read-back, and append
+ * `served` for each one that shows up. This is the longer read-back the sweep deliberately defers
+ * (publishing.md: lags reach 252–368 s). A TERMINAL class (blocked/deleted/staged/missing) is a
+ * spent number — waiting cannot help, so it is skipped. Returns the names confirmed.
+ */
+export async function settleUnserved(input) {
+    const waiting = pendingEntries(input.entries).unserved.filter((e) => !isTerminalClass(e.cls));
+    const confirmed = await Promise.all(waiting.map(async (e) => {
+        const readback = await verifyPublishedVersion({
+            registry: input.registryFor(e.name),
+            name: e.name,
+            version: e.version,
+            budgetMs: input.budgetMs,
+            authorization: input.authorization,
+            fetchImpl: input.fetchImpl,
+            sleep: input.sleep,
+            now: input.now,
+            log: input.log,
+        });
+        if (!readback.confirmed)
+            return undefined;
+        appendLedger(input.ledgerPath, { ev: 'served', name: e.name, version: e.version });
+        return `${e.name}@${e.version}`;
+    }));
+    return confirmed.filter((x) => x !== undefined);
+}
 export function renderLedgerSummary(entries, ref) {
-    const served = new Set(entries.filter((e) => e.ev === 'served').map((e) => `${e.name}@${e.version}`));
-    const unserved = entries.filter((e) => e.ev === 'unserved' && !served.has(`${e.name}@${e.version}`));
-    const held = entries.filter((e) => e.ev === 'held');
+    const { unserved, held } = pendingEntries(entries);
     if (unserved.length === 0 && held.length === 0)
         return undefined;
     const lines = ['### npm versions that were accepted but are not installable', ''];
@@ -205,7 +245,7 @@ export function renderLedgerSummary(entries, ref) {
         for (const e of held)
             lines.push(`| \`${e.name}\` | ${e.version} | ${summariseReasons(e.reasons)} |`);
         lines.push('', 'Once the dependencies above are served by npm (a `validating` version appears on its own, or is approved/released by a maintainer), publish the held set with:', '', '```sh', `gh workflow run release.yml --ref ${ref} -f skip_publish=false -f only='${[...new Set(held.map((e) => e.name))].join(' ')}'`, '```');
-        if (entries.some((e) => e.ev === 'unserved' && (e.cls === 'blocked' || e.cls === 'deleted'))) {
+        if (unserved.some((e) => e.cls === 'blocked' || e.cls === 'deleted')) {
             lines.push('', 'A `blocked` or `deleted` version is a spent number: re-running the release cannot serve it, the package needs a version bump.');
         }
     }

package/lib/utils/ship/app-runtime.d.ts

@@ -49,6 +49,13 @@ export interface ResolveRuntimeOptions {
      * is Bun's global-cache behaviour, which is otherwise unreachable from Node.
      */
     resolve?: ResolveInstalledPackageOptions['resolve'];
+    /**
+     * The directory of a `@gjsify/gtk-runtime-<target>` package that
+     * {@link acquireGtkRuntime} fetched for THIS run — the last candidate, after
+     * everything the author installed or pointed at. See `gtk-runtime-acquire.ts`
+     * for why it is fetched rather than installed.
+     */
+    fetchedGtkRuntimeDir?: string;
 }
 /**
  * Locate the relocated GTK closure for `target`, or `null`.
@@ -68,7 +75,11 @@ export interface ResolveRuntimeOptions {
  *     for a ship run.
  *  3. the sibling monorepo directory `../gtk-runtime-<target>/gtk`, which is what
  *     an in-repo `npm run build:bundle` writes.
- *  4. the published `@gjsify/gtk-runtime-<target>` package's `gtk/`.
+ *  4. the published `@gjsify/gtk-runtime-<target>` package's `gtk/`, when the
+ *     author installed it.
+ *  5. the same package fetched for this run (`fetchedGtkRuntimeDir`) — NOT in
+ *     node-gi's probe, because node-gi never fetches: it finds the closure inside
+ *     the `.app` this function put it in, and the layout there is the same.
  *
  * A candidate counts only when it holds BOTH the loadable-code directory and the
  * typelib directory — node-gi's own probe, restated here rather than weakened,
@@ -195,6 +206,10 @@ export interface StageAppRuntimeInput {
         nodePath: string;
         licensePath: string;
     } | null;
+    /** See {@link ResolveRuntimeOptions.fetchedGtkRuntimeDir}. */
+    fetchedGtkRuntimeDir?: string;
+    /** Why the fetch produced nothing — named in the `missing` line, so the cause is not guessed at. */
+    gtkFetchFailure?: string;
 }
 /**
  * Stage the interpreter, the GTK closure and the addon into one bundle.

package/lib/utils/ship/app-runtime.js

@@ -123,7 +123,11 @@ export const NODE_GI_PACKAGE = '@gjsify/node-gi';
  *     for a ship run.
  *  3. the sibling monorepo directory `../gtk-runtime-<target>/gtk`, which is what
  *     an in-repo `npm run build:bundle` writes.
- *  4. the published `@gjsify/gtk-runtime-<target>` package's `gtk/`.
+ *  4. the published `@gjsify/gtk-runtime-<target>` package's `gtk/`, when the
+ *     author installed it.
+ *  5. the same package fetched for this run (`fetchedGtkRuntimeDir`) — NOT in
+ *     node-gi's probe, because node-gi never fetches: it finds the closure inside
+ *     the `.app` this function put it in, and the layout there is the same.
  *
  * A candidate counts only when it holds BOTH the loadable-code directory and the
  * typelib directory — node-gi's own probe, restated here rather than weakened,
@@ -155,6 +159,12 @@ export function resolveGtkRuntime(target, options = {}) {
     const entry = resolveStagedPackage(packageName, options);
     if (entry !== null)
         candidates.push({ source: packageName, dir: join(dirname(entry), 'gtk') });
+    if (options.fetchedGtkRuntimeDir !== undefined) {
+        candidates.push({
+            source: `${packageName} (fetched for this ship run)`,
+            dir: join(options.fetchedGtkRuntimeDir, 'gtk'),
+        });
+    }
     for (const candidate of candidates) {
         const libDir = join(candidate.dir, nativeSubdir);
         const typelibDir = join(candidate.dir, 'girepository-1.0');
@@ -340,8 +350,10 @@ export function stageAppRuntime(input) {
         // resolver then refuses -- a hint that is wrong is worse than none,
         // because it costs the reader the time to follow it first.
         const nativeSubdir = input.target.startsWith('win32-') ? 'bin' : 'lib';
-        missing.push(`no GTK closure — install \`${gtkRuntimePackageName(input.target)}\` (or point ` +
-            `\`GJSIFY_GTK_RUNTIME\` at a bundle directory holding \`${nativeSubdir}/\` and \`girepository-1.0/\`)`);
+        const why = input.gtkFetchFailure === undefined ? '' : ` — fetching it failed: ${input.gtkFetchFailure}`;
+        missing.push(`no GTK closure${why} — point \`GJSIFY_GTK_RUNTIME\` at a bundle directory holding ` +
+            `\`${nativeSubdir}/\` and \`girepository-1.0/\`, or install \`${gtkRuntimePackageName(input.target)}\` ` +
+            'where the build can reach it');
     }
     // node-gi's JavaScript, which the bundle `require`s by name. Staged whenever
     // the package is resolvable and reported separately from the addon: a bundle
@@ -394,6 +406,8 @@ function discoveryOptions(input) {
         options.env = input.env;
     if (input.resolve !== undefined)
         options.resolve = input.resolve;
+    if (input.fetchedGtkRuntimeDir !== undefined)
+        options.fetchedGtkRuntimeDir = input.fetchedGtkRuntimeDir;
     return options;
 }
 /**

package/lib/utils/ship/gtk-runtime-acquire.d.ts

@@ -0,0 +1,36 @@
+import { type GtkRuntimeTarget, type ResolveRuntimeOptions } from './app-runtime.js';
+export type AcquiredGtkRuntime = 
+/** Something already resolves — nothing was fetched, and nothing will be. */
+{
+    kind: 'present';
+}
+/** Fetched; `dir` is the PACKAGE directory, holding `gtk/`. */
+ | {
+    kind: 'fetched';
+    dir: string;
+}
+/** Could not be had; `reason` is what to tell the person, verbatim. */
+ | {
+    kind: 'failed';
+    reason: string;
+};
+export interface AcquireGtkRuntimeInput {
+    target: GtkRuntimeTarget;
+    /** The version to fetch: the CLI's own, because addon and closure are a matched pair. */
+    version: string;
+    /** The same discovery options the staging step will use — so "present" means what it will mean there. */
+    discovery?: ResolveRuntimeOptions;
+    /**
+     * Fetch a package spec into a cache and return its directory. Injected: the
+     * real one is `ensurePkgDir`, and a test must not touch a registry.
+     */
+    ensure: (spec: string) => Promise<string>;
+    /** One progress line. The closure is ~100 MB, so a silent first run looks like a hang. */
+    log?: (message: string) => void;
+}
+/**
+ * Make sure a GTK closure is reachable for `target`, fetching it only if nothing
+ * else provides one. Never throws: a ship run with no closure is a PARTIAL result
+ * that `stageAppRuntime` reports, not an error (see its doc).
+ */
+export declare function acquireGtkRuntime(input: AcquireGtkRuntimeInput): Promise<AcquiredGtkRuntime>;

package/lib/utils/ship/gtk-runtime-acquire.js

@@ -0,0 +1,59 @@
+// Getting the GTK closure for a ship run when the project does not carry it.
+//
+// WHY IT IS FETCHED AND NOT INSTALLED. `@gjsify/gtk-runtime-<target>` is 100 MB of
+// GLib, GObject, GTK and friends, and a project that lists it — as
+// `optionalDependencies`, which the `os`/`cpu` gate turns into "installed on every
+// Mac" — gets it into its own `node_modules`. On macOS that breaks every build and
+// every run that goes through a Homebrew GJS. Every darwin prebuild
+// carries the rpath `@loader_path` → `…/gtk-runtime-darwin-<arch>/gtk/lib` →
+// `<brew>/lib` (ADR 0023: bundle before system, `docs/prebuilds.md`), so the first
+// `dlopen` out of `node_modules/@gjsify/*-native-darwin-*` finds the bundle's
+// GLib/GObject beside the one `gjs` already loaded from Homebrew: two GObject type
+// registries in one process, which shows as `No signal 'context_response' on
+// object 'GVolumeMonitor'` and a segfault, or as `GNotificationCenterDelegate is
+// implemented in both …`. The invariant ADR 0023 names — one registry per process
+// — is violated by the dev tree itself.
+//
+// The closure is only ever needed at the moment it is COPIED into a bundle, so it
+// is acquired then: into the dlx cache (`ensurePkgDir`, the same machinery
+// `gjsify showcase` already uses for the same package), never into the project.
+// What this does NOT change: the search order in `resolveGtkRuntime()` keeps its
+// four existing candidates, so a project that still installs the package ships
+// exactly as before — it merely stays exposed to the dev-tree failure above until
+// it drops the dependency.
+//
+// EXACT VERSION, no range and no fallback. The addon's `@rpath` is
+// `@loader_path/gtk/lib` — addon and closure are a matched pair published from the
+// same release — so "the nearest published version" would be a guess about GTK ABI
+// that `assertPayloadMatchesArch` cannot check. A CLI version with no published
+// runtime (a dev or `next` build) fails with the reason named, and
+// `GJSIFY_GTK_RUNTIME` is the way past it.
+import { gtkRuntimePackageName, resolveGtkRuntime, } from './app-runtime.js';
+/**
+ * Make sure a GTK closure is reachable for `target`, fetching it only if nothing
+ * else provides one. Never throws: a ship run with no closure is a PARTIAL result
+ * that `stageAppRuntime` reports, not an error (see its doc).
+ */
+export async function acquireGtkRuntime(input) {
+    const discovery = input.discovery ?? {};
+    if (resolveGtkRuntime(input.target, discovery) !== null)
+        return { kind: 'present' };
+    const name = gtkRuntimePackageName(input.target);
+    const spec = `${name}@${input.version}`;
+    input.log?.(`${name} is not installed here, and is not meant to be — fetching ${spec} into the cache ` +
+        '(about 100 MB, once)');
+    let dir;
+    try {
+        dir = await input.ensure(spec);
+    }
+    catch (error) {
+        return { kind: 'failed', reason: error instanceof Error ? error.message : String(error) };
+    }
+    // The same completeness probe the staging step applies, so a package that
+    // resolved but holds no `gtk/` (an unpopulated checkout, a truncated cache
+    // entry) is reported HERE, with its name, instead of as a bare "no GTK closure".
+    if (resolveGtkRuntime(input.target, { ...discovery, fetchedGtkRuntimeDir: dir }) === null) {
+        return { kind: 'failed', reason: `${spec} was fetched to ${dir} but holds no complete gtk/ closure` };
+    }
+    return { kind: 'fetched', dir };
+}