@gjsify/cli 0.64.3-next.262 → 0.64.4

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

@@ -0,0 +1,37 @@
+/** HTTP statuses worth retrying — npm-side transient/overload conditions. */
+export declare const TRANSIENT_STATUSES: ReadonlySet<number>;
+export declare const isTransientStatus: (status: number) => boolean;
+/** Longest single wait, whether it came from the backoff or from a `Retry-After`. */
+export declare const MAX_RETRY_DELAY_MS = 30000;
+/**
+ * Milliseconds a `Retry-After` header asks for: delta-seconds or an HTTP date. `undefined` when
+ * absent or unparseable.
+ */
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+/** The wait before retry `attempt` (0-based): `Retry-After` if the server sent one, else doubling backoff; capped. */
+export declare function retryDelayMs(attempt: number, baseMs: number, retryAfter?: string | null): number;
+export interface TransientRetryOptions {
+    /** Retries after the first attempt. Default {@link DEFAULT_TRANSIENT_RETRIES}. */
+    retries?: number;
+    /** Base backoff in ms, doubling per attempt. Default {@link DEFAULT_TRANSIENT_BASE_MS}. Tests pass 0. */
+    baseMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (msg: string) => void;
+}
+/**
+ * Five retries at 2/4/8/16/30 s: ~60 s of patience per package. Long enough to ride out a blip,
+ * short enough that a real outage fails the sweep in a minute instead of stalling 232 packages
+ * behind it — the failure is then a red job, recovered by a re-run (`--tolerate-republish`).
+ */
+export declare const DEFAULT_TRANSIENT_RETRIES = 5;
+export declare const DEFAULT_TRANSIENT_BASE_MS = 2000;
+export interface TransientRetryResult {
+    response: Response;
+    /** How many retries were spent; >0 means an earlier attempt may have landed. */
+    retried: number;
+}
+/**
+ * Run `doFetch`, retrying a thrown network error or a transient status. Returns the last response
+ * once the budget is spent (the caller interprets the 5xx); rethrows the last network error.
+ */
+export declare function fetchWithTransientRetry(doFetch: () => Promise<Response>, opts?: TransientRetryOptions): Promise<TransientRetryResult>;

package/lib/utils/transient-retry.js

@@ -0,0 +1,72 @@
+// Bounded retry for npm-side TRANSIENT failures, shared by the publish PUT and the OIDC exchange.
+//
+// THE INCIDENT (release run 39737673761, v0.64.3). During an npm incident the registry answered
+// the FIRST PUT of the sweep (`@gjsify/adwaita-core`) with `503 {"error":"Service Unavailable"}`.
+// `gjsify publish` retried only the OTP challenge, so it exited 1, `foreach --exec` threw on the
+// non-zero child, and the sweep stopped with 0 of 232 packages published. The OIDC exchange
+// already retried a 503 (v0.7.3, `@gjsify/process`); the PUT never did.
+//
+// A 5xx after a PUT may still have LANDED, so a retry is only safe because the caller treats the
+// answer to the retried PUT idempotently (409 / 403 "previously published" → the republish path).
+/** HTTP statuses worth retrying — npm-side transient/overload conditions. */
+export const TRANSIENT_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+export const isTransientStatus = (status) => TRANSIENT_STATUSES.has(status);
+/** Longest single wait, whether it came from the backoff or from a `Retry-After`. */
+export const MAX_RETRY_DELAY_MS = 30_000;
+/**
+ * Milliseconds a `Retry-After` header asks for: delta-seconds or an HTTP date. `undefined` when
+ * absent or unparseable.
+ */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (/^\d+(?:\.\d+)?$/.test(trimmed))
+        return Math.round(Number(trimmed) * 1000);
+    const at = Date.parse(trimmed);
+    return Number.isNaN(at) ? undefined : Math.max(0, at - now);
+}
+/** The wait before retry `attempt` (0-based): `Retry-After` if the server sent one, else doubling backoff; capped. */
+export function retryDelayMs(attempt, baseMs, retryAfter) {
+    const asked = parseRetryAfter(retryAfter);
+    return Math.min(asked ?? baseMs * 2 ** attempt, MAX_RETRY_DELAY_MS);
+}
+/**
+ * Five retries at 2/4/8/16/30 s: ~60 s of patience per package. Long enough to ride out a blip,
+ * short enough that a real outage fails the sweep in a minute instead of stalling 232 packages
+ * behind it — the failure is then a red job, recovered by a re-run (`--tolerate-republish`).
+ */
+export const DEFAULT_TRANSIENT_RETRIES = 5;
+export const DEFAULT_TRANSIENT_BASE_MS = 2000;
+/**
+ * Run `doFetch`, retrying a thrown network error or a transient status. Returns the last response
+ * once the budget is spent (the caller interprets the 5xx); rethrows the last network error.
+ */
+export async function fetchWithTransientRetry(doFetch, opts = {}) {
+    const retries = opts.retries ?? DEFAULT_TRANSIENT_RETRIES;
+    const baseMs = opts.baseMs ?? DEFAULT_TRANSIENT_BASE_MS;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let attempt = 0;; attempt++) {
+        let response;
+        let failure;
+        try {
+            response = await doFetch();
+        }
+        catch (err) {
+            failure = err;
+        }
+        if (response && !isTransientStatus(response.status))
+            return { response, retried: attempt };
+        if (attempt >= retries) {
+            if (response)
+                return { response, retried: attempt };
+            throw failure;
+        }
+        const delay = retryDelayMs(attempt, baseMs, response?.headers.get('retry-after'));
+        const what = response
+            ? `${response.status} ${response.statusText}`
+            : `network error: ${failure instanceof Error ? failure.message : String(failure)}`;
+        opts.log?.(`transient ${what} (attempt ${attempt + 1}/${retries + 1}), retrying in ${delay}ms`);
+        await sleep(delay);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.64.3-next.262",
+    "version": "0.64.4",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,22 +142,22 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/blueprint": "0.64.3-next.262",
-        "@gjsify/buffer": "0.64.3-next.262",
-        "@gjsify/create-app": "0.64.3-next.262",
-        "@gjsify/node-globals": "0.64.3-next.262",
-        "@gjsify/node-polyfills": "0.64.3-next.262",
-        "@gjsify/npm-registry": "0.64.3-next.262",
-        "@gjsify/resolve-npm": "0.64.3-next.262",
-        "@gjsify/rolldown-plugin-gjsify": "0.64.3-next.262",
-        "@gjsify/vite-plugin-blueprint": "0.64.3-next.262",
-        "@gjsify/rolldown-plugin-pnp": "0.64.3-next.262",
-        "@gjsify/semver": "0.64.3-next.262",
-        "@gjsify/tar": "0.64.3-next.262",
-        "@gjsify/tsc": "0.64.3-next.262",
-        "@gjsify/utils": "0.64.3-next.262",
-        "@gjsify/web-polyfills": "0.64.3-next.262",
-        "@gjsify/workspace": "0.64.3-next.262",
+        "@gjsify/blueprint": "^0.64.4",
+        "@gjsify/buffer": "^0.64.4",
+        "@gjsify/create-app": "^0.64.4",
+        "@gjsify/node-globals": "^0.64.4",
+        "@gjsify/node-polyfills": "^0.64.4",
+        "@gjsify/npm-registry": "^0.64.4",
+        "@gjsify/resolve-npm": "^0.64.4",
+        "@gjsify/rolldown-plugin-gjsify": "^0.64.4",
+        "@gjsify/vite-plugin-blueprint": "^0.64.4",
+        "@gjsify/rolldown-plugin-pnp": "^0.64.4",
+        "@gjsify/semver": "^0.64.4",
+        "@gjsify/tar": "^0.64.4",
+        "@gjsify/tsc": "^0.64.4",
+        "@gjsify/utils": "^0.64.4",
+        "@gjsify/web-polyfills": "^0.64.4",
+        "@gjsify/workspace": "^0.64.4",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -166,13 +166,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "0.64.3-next.262",
+        "@gjsify/unit": "^0.64.4",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "0.64.3-next.262",
-        "@gjsify/rolldown-native": "0.64.3-next.262"
+        "@gjsify/oxfmt-native": "^0.64.4",
+        "@gjsify/rolldown-native": "^0.64.4"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {
@@ -191,6 +191,5 @@
     "bugs": {
         "url": "https://github.com/gjsify/gjsify/issues"
     },
-    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/infra/cli#readme",
-    "gitHead": "0f5ca82aab25bf9df8d1e790d28483b1f90fe3a9"
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/infra/cli#readme"
 }