@gjsify/cli 0.44.0 → 0.46.0

package/lib/utils/onboard-probe.js

@@ -11,6 +11,69 @@
 import { DEFAULT_REGISTRY, registryFor } from '@gjsify/npm-registry';
 import { classifyTrustList, trustUrl } from './trust-registry.js';
 export const PROBE_RETRY_DELAY_MS = 400;
+/**
+ * A 429 is npm asking to be asked later — never an answer about the package.
+ *
+ * Measured on the real 703-package sweep of `gjsify/types` at the default
+ * concurrency: the first 662 reads answered and the LAST 41 came back `429`, so
+ * the plan said `41 unreadable` for packages whose state nobody had actually
+ * failed to determine. The tail of an alphabetical list is exactly where a
+ * cumulative rate limit lands, which makes the damage look like a property of
+ * those packages.
+ *
+ * Waiting is the whole fix, and it has to be bounded: an unbounded wait turns a
+ * throttled sweep into a hang with no output.
+ */
+/**
+ * A TIME budget, not an attempt count — and generous, because npm tells us
+ * nothing.
+ *
+ * The attempt count was the wrong unit and the real sweep proved it: 4 attempts
+ * with a doubling 2s base is 30 seconds of patience, npm's window is longer than
+ * that, so every in-flight request spent its budget inside one cooldown and
+ * `Done: 502 trusted … 73 failed` — all 73 at the tail, all 429, none of them a
+ * fact about those packages.
+ *
+ * With no `Retry-After` and no rate-limit headers to read (measured), waiting is
+ * the only instrument there is. Five minutes per request is worth it: the
+ * alternative is failing packages that then need another sweep, which is itself
+ * throttled. Bounded all the same, so a throttled sweep still ENDS.
+ */
+export const RATE_LIMIT_MAX_WAIT_MS = 300_000;
+export const RATE_LIMIT_BASE_DELAY_MS = 2000;
+/** Ceiling for a single backoff step, so escalation stays legible. */
+export const RATE_LIMIT_MAX_STEP_MS = 60_000;
+/**
+ * What npm told us about pacing on a 429 — verbatim, so the answer to "how fast
+ * may we go" comes from the registry rather than from a guess.
+ *
+ * Measured 2026-08-28: npm serves NO `X-RateLimit-*` headers on ordinary
+ * responses, so there is no budget to read ahead of time. `Retry-After` on the
+ * 429 itself is the only channel, and whether npm populates it on the trust
+ * endpoint is exactly what this reports the first time it happens.
+ */
+export function describeRateLimitHeaders(headers) {
+    if (!headers)
+        return 'no headers captured';
+    const seen = [];
+    headers.forEach((value, key) => {
+        if (/^retry-after$/i.test(key) || /ratelimit/i.test(key))
+            seen.push(`${key}: ${value}`);
+    });
+    return seen.length > 0 ? seen.join(', ') : 'npm sent no Retry-After and no rate-limit headers';
+}
+/** Seconds to wait per npm's `Retry-After`, or null when it said nothing usable. */
+export function retryAfterMs(headers) {
+    const raw = headers?.get('retry-after');
+    if (!raw)
+        return null;
+    const secs = Number.parseInt(raw.trim(), 10);
+    // Only the delta-seconds form. The HTTP-date form is legal and npm does not
+    // send it; guessing at a date here would be a second clock to get wrong.
+    if (!Number.isFinite(secs) || secs < 0)
+        return null;
+    return secs * 1000;
+}
 /**
  * Does the registry serve a packument for this name?
  *
@@ -67,6 +130,84 @@ export function actionForState(state) {
 function defaultSleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * A cool-down shared by every in-flight request of a sweep.
+ *
+ * Retrying ONE throttled request in isolation is not enough, and the measured
+ * run shows why: at serial pace `gjsify/types` was already being 429'd, so every
+ * other worker kept hammering the registry through the very window the retry was
+ * waiting out — and the retry budget then expired against a limit nobody had
+ * stopped provoking. `trust failed (HTTP 429)` was the result.
+ *
+ * A 429 anywhere therefore pauses EVERYWHERE. That also makes concurrency safe
+ * to raise: the sweep self-paces down to whatever npm is willing to serve
+ * instead of the operator guessing a number.
+ */
+export class RateLimitGate {
+    until = 0;
+    now;
+    sleeper;
+    constructor(opts = {}) {
+        this.now = opts.now ?? (() => Date.now());
+        this.sleeper = opts.sleep ?? defaultSleep;
+    }
+    /** Block while a cool-down is in effect. */
+    async wait() {
+        const remaining = this.until - this.now();
+        if (remaining > 0)
+            await this.sleeper(remaining);
+    }
+    /** Hold every request back for at least `ms` from now. */
+    penalize(ms) {
+        this.until = Math.max(this.until, this.now() + ms);
+    }
+    /** Milliseconds still owed, for tests and for reporting. */
+    remainingMs() {
+        return Math.max(0, this.until - this.now());
+    }
+}
+/**
+ * Issue a request, waiting out an HTTP 429 rather than reporting it as a state.
+ *
+ * Used by BOTH the probe GET and the act-phase trust POST, because a sweep long
+ * enough to be throttled on reads is long enough to be throttled on writes, and
+ * a throttled POST would otherwise be recorded as `trust failed (HTTP 429)` —
+ * a failure attributed to the package instead of to the pacing.
+ *
+ * Bounded on purpose: it returns the last 429 once the budget is spent, so the
+ * caller reports "unreadable" rather than hanging. `Retry-After` wins over the
+ * exponential backoff whenever npm sends a usable one.
+ */
+export async function requestWaitingOutRateLimit(request, method, url, body, opts = {}) {
+    const sleep = opts.sleep ?? defaultSleep;
+    const budgetMs = opts.maxRateLimitWaitMs ?? RATE_LIMIT_MAX_WAIT_MS;
+    const baseDelay = opts.rateLimitBaseDelayMs ?? RATE_LIMIT_BASE_DELAY_MS;
+    const gate = opts.gate;
+    // Respect a cool-down somebody else is already serving BEFORE spending an
+    // attempt. Without this the sweep keeps provoking the limit it is waiting on.
+    if (gate)
+        await gate.wait();
+    let res = await request(method, url, body);
+    let waited = 0;
+    for (let attempt = 0; res.status === 429 && waited < budgetMs; attempt++) {
+        const advised = retryAfterMs(res.headers);
+        const step = Math.min(advised ?? baseDelay * 2 ** attempt, RATE_LIMIT_MAX_STEP_MS);
+        // Never overshoot the budget: the last wait is whatever is left of it.
+        const delay = Math.min(step, budgetMs - waited);
+        opts.onRateLimit?.({
+            url,
+            headers: describeRateLimitHeaders(res.headers),
+            waitMs: delay,
+            fromRetryAfter: advised !== null,
+        });
+        // Tell everyone, not just this call.
+        gate?.penalize(delay);
+        await (gate ? gate.wait() : sleep(delay));
+        waited += delay;
+        res = await request(method, url, body);
+    }
+    return res;
+}
 /**
  * Read one package's published + trust state through the SHARED trust requester.
  * A surviving `auth-required` means the 401 was not an answerable OTP challenge —
@@ -77,10 +218,11 @@ export async function probeTrustState(request, ws, ctx, opts = {}) {
     const registry = ctx.registryOverride ?? registryFor(ws.name, ctx.npmrc) ?? DEFAULT_REGISTRY;
     const url = trustUrl(registry, ws.name);
     const classifyOpts = { repository: ctx.repository, workflow: ctx.workflow };
-    let res = await request('GET', url);
+    const sleep = opts.sleep ?? defaultSleep;
+    // A 429 is not an answer — wait it out BEFORE classifying anything.
+    let res = await requestWaitingOutRateLimit(request, 'GET', url, undefined, opts);
     let state = classifyTrustList(res.status, res.json, classifyOpts);
     if (state === 'auth-required' && opts.retryOn401 !== false) {
-        const sleep = opts.sleep ?? defaultSleep;
         await sleep(opts.retryDelayMs ?? PROBE_RETRY_DELAY_MS);
         res = await request('GET', url);
         state = classifyTrustList(res.status, res.json, classifyOpts);
@@ -123,8 +265,15 @@ export async function probeTrustState(request, ws, ctx, opts = {}) {
 export async function probeAllTrustStates(request, selected, concurrency, ctx, opts = {}) {
     if (selected.length === 0)
         return [];
-    const first = await probeTrustState(request, selected[0], ctx, opts);
-    const rest = await mapWithConcurrency(selected.slice(1), Math.max(1, concurrency), (ws) => probeTrustState(request, ws, ctx, opts));
+    const total = selected.length;
+    let done = 0;
+    const report = (plan) => {
+        done++;
+        opts.onProgress?.(done, total, plan);
+        return plan;
+    };
+    const first = report(await probeTrustState(request, selected[0], ctx, opts));
+    const rest = await mapWithConcurrency(selected.slice(1), Math.max(1, concurrency), async (ws) => report(await probeTrustState(request, ws, ctx, opts)));
     return [first, ...rest];
 }
 /** Map with bounded concurrency, preserving input order in the result. */

package/lib/utils/prompt-output.d.ts

@@ -0,0 +1,12 @@
+type Writer = (text: string) => void;
+/** How many prompts are currently on screen. Exposed for tests. */
+export declare function promptDepth(): number;
+/** Mark a prompt as open; every `writeAroundPrompt` is held until it closes. */
+export declare function beginPrompt(): void;
+/** Close a prompt and flush anything held while it was open. */
+export declare function endPrompt(write?: Writer): void;
+/** Write now, or hold until the open prompt closes. */
+export declare function writeAroundPrompt(text: string, write?: Writer): void;
+/** Test seam: forget any held output and reset the depth. */
+export declare function resetPromptOutput(): void;
+export {};

package/lib/utils/prompt-output.js

@@ -0,0 +1,54 @@
+// Stdout arbitration between a live prompt and everything else writing to it.
+//
+// A prompt owns the last line of the terminal. On a TTY `prompt.ts` runs in RAW
+// mode and echoes each keystroke by hand, so the cursor sits mid-line with no
+// newline pending — and any other writer lands INSIDE what the user is typing:
+//
+//     Enter a NEW OTP:   npm rate limit hit. npm sent no Retry-After …
+//     228000
+//
+// (measured on a real `gjsify onboard` sweep: a rate-limit notice from a
+// concurrent worker spliced into the digits being entered, leaving the typed
+// code visually split across two lines).
+//
+// The rule is arbitration, not silence: a message that arrives during a prompt
+// is HELD and flushed the moment the prompt closes. Dropping it would trade a
+// cosmetic problem for a lost one, and the messages that show up here are
+// exactly the ones explaining why the sweep is slow.
+let depth = 0;
+const held = [];
+/** How many prompts are currently on screen. Exposed for tests. */
+export function promptDepth() {
+    return depth;
+}
+/** Mark a prompt as open; every `writeAroundPrompt` is held until it closes. */
+export function beginPrompt() {
+    depth++;
+}
+/** Close a prompt and flush anything held while it was open. */
+export function endPrompt(write = defaultWrite) {
+    depth = Math.max(0, depth - 1);
+    if (depth > 0)
+        return;
+    if (held.length === 0)
+        return;
+    const pendingLines = held.splice(0, held.length);
+    for (const line of pendingLines)
+        write(line);
+}
+/** Write now, or hold until the open prompt closes. */
+export function writeAroundPrompt(text, write = defaultWrite) {
+    if (depth > 0) {
+        held.push(text);
+        return;
+    }
+    write(text);
+}
+function defaultWrite(text) {
+    process.stdout.write(text);
+}
+/** Test seam: forget any held output and reset the depth. */
+export function resetPromptOutput() {
+    depth = 0;
+    held.length = 0;
+}

package/lib/utils/prompt.js

@@ -15,6 +15,7 @@
 //
 // Non-TTY stdin (piped input, CI) keeps a plain line read so
 // `printf 'user\npass\n' | gjsify login` still works.
+import { beginPrompt, endPrompt } from './prompt-output.js';
 const CTRL_C = '\x03'; // ETX (Ctrl-C)
 const DEL = '\x7f'; // DEL (Backspace on most terminals)
 const BACKSPACE = '\x08'; // BS
@@ -98,8 +99,18 @@ async function runRawSession(fn) {
     stdin.setEncoding('utf-8');
     stdin.on('data', onData);
     const read = (question, mask) => new Promise((resolve) => {
+        // A prompt owns the last line: hold back every other writer until it
+        // closes, or their output lands inside the digits being typed.
+        beginPrompt();
         out.write(question);
-        pending = { mask, buf: '', resolve };
+        pending = {
+            mask,
+            buf: '',
+            resolve: (value) => {
+                endPrompt();
+                resolve(value);
+            },
+        };
     });
     try {
         return await fn(read);
@@ -138,8 +149,17 @@ function readLine() {
 /** Print a question and read one visible line. */
 export async function promptLine(question) {
     if (!isTtyStdin()) {
+        // Non-TTY holds back other writers too: the interleaving is not visible
+        // here, but a transcript in which a notice sits between the question and
+        // the answer is just as hard to read afterwards.
+        beginPrompt();
         process.stdout.write(question);
-        return readLine();
+        try {
+            return await readLine();
+        }
+        finally {
+            endPrompt();
+        }
     }
     return runRawSession((read) => read(question, false));
 }

package/lib/utils/publishable-packages.d.ts

@@ -4,7 +4,7 @@ import type { Workspace } from '@gjsify/workspace';
  * workspaces. Extend this the moment a new such group appears — the list is the
  * only thing standing between one and a silently broken first release.
  */
-export declare const NON_WORKSPACE_PUBLISHABLE_DIRS: readonly [readonly ["packages", "node-gi"], readonly ["packages", "napi"]];
+export declare const NON_WORKSPACE_PUBLISHABLE_DIRS: readonly [readonly ["packages", "node-gi"], readonly ["packages", "napi"], readonly ["packages", "node-runtime"]];
 /**
  * Publishable packages in {@link NON_WORKSPACE_PUBLISHABLE_DIRS}, shaped as
  * `Workspace` entries so callers can treat them like any other package.

package/lib/utils/publishable-packages.js

@@ -19,6 +19,7 @@ import { dirname, join } from 'node:path';
 export const NON_WORKSPACE_PUBLISHABLE_DIRS = [
     ['packages', 'node-gi'], // @gjsify/node-gi + the @gjsify/gtk-runtime-* bundles
     ['packages', 'napi'], // @gjsify/napi (the N-API host in GJS, own napi.yml)
+    ['packages', 'node-runtime'], // the @gjsify/node-runtime-* bundled Node interpreters
 ];
 /**
  * Publishable packages in {@link NON_WORKSPACE_PUBLISHABLE_DIRS}, shaped as

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

@@ -14,3 +14,59 @@ export interface ResolveNpmPackageOptions {
  * `pathToFileURL().href` before a dynamic `import(...)`.
  */
 export declare function resolveNpmPackage(specifier: string, opts?: ResolveNpmPackageOptions): string | null;
+/**
+ * The anchor a resolution was asked from — see {@link resolveInstalledPackage}.
+ *
+ * `'nowhere'` is a directory inside no project. Under Node it can only fail;
+ * under Bun it is where the sixth anchor shows itself.
+ */
+export type PackageAnchor = 'project' | 'nowhere';
+export interface ResolveInstalledPackageOptions extends ResolveNpmPackageOptions {
+    /**
+     * TEST SEAM — resolve `specifier` from one anchor, or `null`.
+     *
+     * Injected so Bun's behaviour below is reproducible from Node: a fake that
+     * answers the SAME path for both anchors is exactly what Bun does for a
+     * package the project never installed, and it is the only way to red this
+     * guard on a runtime that does not have the defect.
+     */
+    resolve?: (specifier: string, anchor: PackageAnchor) => string | null;
+}
+/**
+ * Resolve a bare specifier the way {@link resolveNpmPackage} does, but refuse an
+ * answer the RUNTIME invented rather than the project provided.
+ *
+ * THE SIXTH ANCHOR, which the list above does not mention because it is not
+ * ours. Bun auto-installs: `createRequire(<anchor>).resolve('<name>')` falls back
+ * to Bun's global install cache instead of throwing, so a package the project
+ * never declared resolves anyway. Measured, bun 1.3.14 vs node 24.19.0, asking
+ * for `@gjsify/node-gi` from a scratch directory:
+ *
+ *     node  →  MODULE_NOT_FOUND
+ *     bun   →  ~/.bun/install/cache/@gjsify/node-gi@0.44.0@@@1/index.js
+ *
+ * And it is not only the empty-directory case. A real project with a
+ * `package.json` and no `node_modules` — a fresh clone, or any Bun project
+ * relying on auto-install — gets the same cache hit, as does one that DECLARES
+ * the dependency without installing it. Only a `package.json` beside an EMPTY
+ * `node_modules` throws.
+ *
+ * WHY THAT MATTERS HERE AND NOT FOR {@link resolveNpmPackage}'s other callers.
+ * Resolving `rolldown` from a cache is fine: it is a TOOL, it runs and is
+ * forgotten. `@gjsify/node-gi`, `@gjsify/gtk-runtime-*` and
+ * `@gjsify/node-runtime-*` are PAYLOAD — `utils/ship/app-runtime.ts` copies
+ * their bytes into a `.app` that gets redistributed. A cache hit there ships
+ * files the project never declared, at whatever version that runtime happened to
+ * cache, and silently: the "install `<name>`" line that should have been printed
+ * never is. It is also #910's shape one level up, an addon paired with a closure
+ * it was not built against.
+ *
+ * THE DISCRIMINATOR IS A CONTROL, not a list of cache paths. Hardcoding
+ * `~/.bun/install/cache` would be this file guessing at another runtime's
+ * layout and going stale the first time Bun moves it. Asking the same question
+ * from a directory inside no project asks the RUNTIME instead: if both anchors
+ * answer with the identical path, the project contributed nothing to that
+ * answer. Under Node the control can only throw, so this is a strict no-op
+ * there — the resolution it returns is byte-identical to `resolveNpmPackage`'s.
+ */
+export declare function resolveInstalledPackage(specifier: string, opts?: ResolveInstalledPackageOptions): string | null;

package/lib/utils/resolve-npm-package.js

@@ -23,6 +23,7 @@
 // (parent-dir walker).
 import { createRequire } from 'node:module';
 import { pathToFileURL } from 'node:url';
+import { tmpdir } from 'node:os';
 import { delimiter, join, resolve } from 'node:path';
 import { findWorkspaceRoot } from './workspace-root.js';
 /**
@@ -92,3 +93,71 @@ function tryResolveFromDir(specifier, dir) {
         return null;
     }
 }
+/**
+ * A directory that is inside no project, for the control probe.
+ *
+ * It does not have to EXIST — measured under bun 1.3.14, a non-existent path
+ * still reaches the cache, so this costs no filesystem access. It must have a
+ * parent, though: an anchor at the filesystem root (`/__r__.js`) throws even
+ * under Bun, which would make the control silently useless.
+ */
+const CONTROL_ANCHOR = join(tmpdir(), '.gjsify-nonexistent-control-anchor', '__gjsify_resolve__.js');
+/**
+ * Resolve a bare specifier the way {@link resolveNpmPackage} does, but refuse an
+ * answer the RUNTIME invented rather than the project provided.
+ *
+ * THE SIXTH ANCHOR, which the list above does not mention because it is not
+ * ours. Bun auto-installs: `createRequire(<anchor>).resolve('<name>')` falls back
+ * to Bun's global install cache instead of throwing, so a package the project
+ * never declared resolves anyway. Measured, bun 1.3.14 vs node 24.19.0, asking
+ * for `@gjsify/node-gi` from a scratch directory:
+ *
+ *     node  →  MODULE_NOT_FOUND
+ *     bun   →  ~/.bun/install/cache/@gjsify/node-gi@0.44.0@@@1/index.js
+ *
+ * And it is not only the empty-directory case. A real project with a
+ * `package.json` and no `node_modules` — a fresh clone, or any Bun project
+ * relying on auto-install — gets the same cache hit, as does one that DECLARES
+ * the dependency without installing it. Only a `package.json` beside an EMPTY
+ * `node_modules` throws.
+ *
+ * WHY THAT MATTERS HERE AND NOT FOR {@link resolveNpmPackage}'s other callers.
+ * Resolving `rolldown` from a cache is fine: it is a TOOL, it runs and is
+ * forgotten. `@gjsify/node-gi`, `@gjsify/gtk-runtime-*` and
+ * `@gjsify/node-runtime-*` are PAYLOAD — `utils/ship/app-runtime.ts` copies
+ * their bytes into a `.app` that gets redistributed. A cache hit there ships
+ * files the project never declared, at whatever version that runtime happened to
+ * cache, and silently: the "install `<name>`" line that should have been printed
+ * never is. It is also #910's shape one level up, an addon paired with a closure
+ * it was not built against.
+ *
+ * THE DISCRIMINATOR IS A CONTROL, not a list of cache paths. Hardcoding
+ * `~/.bun/install/cache` would be this file guessing at another runtime's
+ * layout and going stale the first time Bun moves it. Asking the same question
+ * from a directory inside no project asks the RUNTIME instead: if both anchors
+ * answer with the identical path, the project contributed nothing to that
+ * answer. Under Node the control can only throw, so this is a strict no-op
+ * there — the resolution it returns is byte-identical to `resolveNpmPackage`'s.
+ */
+export function resolveInstalledPackage(specifier, opts = {}) {
+    const resolve = opts.resolve ??
+        ((spec, anchor) => anchor === 'project'
+            ? resolveNpmPackage(spec, { cwd: opts.cwd, bundleUrl: opts.bundleUrl })
+            : tryResolveFromFile(spec, CONTROL_ANCHOR));
+    const hit = resolve(specifier, 'project');
+    if (hit === null)
+        return null;
+    const control = resolve(specifier, 'nowhere');
+    return control !== null && control === hit ? null : hit;
+}
+/** `createRequire(<file>).resolve(specifier)`, or `null`. The file need not exist. */
+function tryResolveFromFile(specifier, anchorFile) {
+    try {
+        return createRequire(pathToFileURL(anchorFile).href).resolve(specifier);
+    }
+    catch {
+        // Not resolvable from a directory in no project — which is the answer
+        // this probe wants on every runtime without a global-cache fallback.
+        return null;
+    }
+}