@gjsify/cli 0.44.0 → 0.45.0

package/lib/utils/onboard-discovery.js

@@ -0,0 +1,178 @@
+// Package-set discovery for `gjsify onboard`, and the ONE thing that decides
+// whether the command is a gjsify-repo chore or a monorepo tool.
+//
+// Onboard used to enumerate exactly one way: `discoverWorkspaces` over the root
+// manifest's `workspaces` globs, plus this repo's two carved-out publishable
+// directories. That set is correct HERE and empty in the repo the sweep is most
+// needed for — `gjsify/types` publishes 703 `@girs/*` packages from a root whose
+// only tracked file is `.gitignore`. There is no manifest, so there are no
+// globs, so `discoverWorkspaces` throws before anything is enumerated.
+//
+// So the package set is now built from up to three SOURCES, and every one of
+// them is REPORTED with its count. That reporting is not decoration: a sweep
+// that writes to npm derives its whole blast radius from this list, and the two
+// ways it goes wrong — enumerating nothing, and enumerating the wrong tree —
+// look identical in a summary that only prints a total. `--packages` matching
+// no directory is a HARD ERROR for the same reason `gjsify foreach --include`
+// is: a filter that selects nothing is a typo or a shell-quoting bug, never an
+// intent (and onboard's own history has the sharper version of this — it once
+// reported "127 already done" while `@gjsify/napi` was simply absent from the
+// list it had built).
+import { existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { discoverWorkspaces } from '@gjsify/workspace';
+import { join } from 'node:path';
+import { mergePublishables } from './publishable-packages.js';
+import { parseRepoFromGitRemote } from './trust-registry.js';
+import { findWorkspaceRoot } from './workspace-root.js';
+/**
+ * The directory the globs and the workspace manifest are resolved against.
+ *
+ * A workspace root wins, because that is what `discoverWorkspaces` needs. When
+ * there is none, the GIT top level is the answer and the cwd is only the last
+ * resort: `--packages '*'` run from anywhere inside a non-workspace monorepo
+ * must mean the same set every time, and resolving it against the cwd would
+ * quietly mean "the packages below wherever I happen to stand".
+ */
+export function resolveRepoRoot(cwd) {
+    const wsRoot = findWorkspaceRoot(cwd);
+    if (wsRoot)
+        return wsRoot;
+    const git = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+    if (git.status === 0) {
+        const top = git.stdout.trim();
+        if (top && existsSync(top))
+            return top;
+    }
+    return cwd;
+}
+/**
+ * Every `--packages` glob must match at least one directory holding a
+ * `package.json` with a name. Throws with the unmatched patterns otherwise.
+ *
+ * Mirrors `gjsify foreach`'s `--include` rule, and matters more here: foreach's
+ * empty selection runs no scripts, while onboard's empty selection is a sweep
+ * that reports itself complete having examined nothing.
+ */
+export function assertEveryPatternMatches(root, patterns) {
+    const unmatched = patterns.filter((pattern) => {
+        try {
+            return discoverWorkspaces(root, { patterns: [pattern] }).length === 0;
+        }
+        catch {
+            return true;
+        }
+    });
+    if (unmatched.length === 0)
+        return;
+    const lines = [
+        `gjsify onboard: --packages matched no package directory (${unmatched.length} of ${patterns.length} pattern(s)) under ${root}:`,
+    ];
+    for (const pattern of unmatched)
+        lines.push(`  ${JSON.stringify(pattern)}`);
+    lines.push('  Patterns are DIRECTORY globs resolved against the repo root, and only `*` is supported', '  (one path segment). A matched directory needs a package.json with a "name".');
+    throw new Error(lines.join('\n'));
+}
+/**
+ * Collect the publishable package set from every source that applies.
+ *
+ * Order is precedence: a real workspace beats a `--packages` hit beats a scanned
+ * directory, deduped by package NAME, so the manifest a build would use is the
+ * manifest the sweep publishes.
+ */
+export function collectOnboardPackages(root, cwd, options = {}) {
+    const sources = [];
+    const packages = [];
+    const seen = new Set();
+    const take = (kind, found, patterns) => {
+        let added = 0;
+        for (const ws of found) {
+            if (!ws.name || seen.has(ws.name))
+                continue;
+            seen.add(ws.name);
+            packages.push(ws);
+            added++;
+        }
+        sources.push({ kind, patterns, count: added });
+    };
+    // 1. The root manifest's own `workspaces` globs, when the repo has them.
+    if (existsSync(join(root, 'package.json'))) {
+        try {
+            take('workspaces', discoverWorkspaces(root, { includeRoot: true }));
+        }
+        catch {
+            // A root package.json without `workspaces` is not an error here —
+            // `--packages` or the scanned dirs may still carry the whole set.
+        }
+    }
+    // 2. Explicit `--packages` globs — the path for a monorepo that is not an
+    //    npm/yarn workspace. Callers run `assertEveryPatternMatches` first, so
+    //    an empty result here can only mean "everything was already covered".
+    if (options.patterns && options.patterns.length > 0) {
+        take('packages', discoverWorkspaces(root, { patterns: [...options.patterns] }), options.patterns);
+    }
+    // 3. This repo's publishable-but-not-workspace directories. A no-op in any
+    //    repo that does not have them; see publishable-packages.ts for the
+    //    incident that put it here.
+    take('scanned-dirs', mergePublishables([], cwd));
+    return { packages, sources };
+}
+/** One-line rendering of where the package set came from. */
+export function describeSources(sources) {
+    return sources
+        .filter((s) => s.count > 0)
+        .map((s) => (s.patterns ? `${s.kind}(${s.patterns.join(',')})=${s.count}` : `${s.kind}=${s.count}`))
+        .join(' + ');
+}
+/** The `owner/repo` a package's own manifest claims, or null if it claims none. */
+export function declaredRepository(ws) {
+    const repo = ws.manifest.repository;
+    const url = typeof repo === 'string' ? repo : repo?.url;
+    if (typeof url !== 'string' || url.length === 0)
+        return null;
+    return parseRepoFromGitRemote(url);
+}
+/**
+ * Refuse to configure a Trusted Publisher for a package whose OWN manifest says
+ * it lives in a different repository.
+ *
+ * This replaces a hardcoded `exclude: ['@girs/*']`, and it is worth more than
+ * the thing it replaces. Measured: `gjsify onboard` in `gjsify/ts-for-gir`
+ * selects 716 packages, ~703 of them the generated `@girs/*` under
+ * `types-dev/*` — which are workspaces there, but are PUBLISHED FROM
+ * `gjsify/types`. Trusting them for `gjsify/ts-for-gir`'s `release.yml` would
+ * point their OIDC exchange at a workflow that never publishes them, i.e. break
+ * the release the sweep exists to protect.
+ *
+ * A name pattern only ever covered the one case somebody had already been bitten
+ * by. The manifest's `repository` is the package's own claim about where it
+ * comes from, so this covers every monorepo that has another project's packages
+ * inside it — vendored, submoduled, or generated.
+ *
+ * Silence is the only safe default in the other direction: a package that
+ * declares NO repository is not evidence of a mismatch, so it passes.
+ */
+export function assertRepositoryAgreement(selected, repository) {
+    const target = repository.toLowerCase();
+    const foreign = selected
+        .map((ws) => ({ ws, declared: declaredRepository(ws) }))
+        .filter((e) => e.declared !== null && e.declared.toLowerCase() !== target);
+    if (foreign.length === 0)
+        return;
+    const byRepo = new Map();
+    for (const { ws, declared } of foreign) {
+        const list = byRepo.get(declared) ?? [];
+        list.push(ws.name);
+        byRepo.set(declared, list);
+    }
+    const lines = [
+        `gjsify onboard: ${foreign.length} selected package(s) declare a DIFFERENT repository than ${repository}:`,
+    ];
+    for (const [repo, names] of byRepo) {
+        const shown = names.slice(0, 5).join(', ');
+        const more = names.length > 5 ? `, … (+${names.length - 5} more)` : '';
+        lines.push(`  ${repo}: ${names.length} package(s) — ${shown}${more}`);
+    }
+    lines.push("  A Trusted Publisher scoped to the wrong repository points that package's OIDC exchange", '  at a workflow that does not publish it, which breaks the release this sweep protects.', '  Either exclude them (--exclude), select only what belongs here (--include), or point', '  --repository at the repo that actually publishes them.');
+    throw new Error(lines.join('\n'));
+}

package/lib/utils/onboard-probe.d.ts

@@ -1,6 +1,6 @@
 import { type NpmrcConfig } from '@gjsify/npm-registry';
 import type { Workspace } from '@gjsify/workspace';
-import type { TrustRequester } from '../commands/trust.js';
+import type { TrustRequester, TrustRequestResult } from '../commands/trust.js';
 import { type TrustState } from './trust-registry.js';
 /** What a package needs, computed from its published + trust state. */
 export type PkgAction = 'skip' | 'trust' | 'publish-and-trust' | 'blocked';
@@ -24,6 +24,38 @@ export interface ProbeOptions {
     retryOn401?: boolean;
     /** Backoff before the single 401 retry. Default {@link PROBE_RETRY_DELAY_MS}. */
     retryDelayMs?: number;
+    /** Total time to spend waiting out HTTP 429s. Default {@link RATE_LIMIT_MAX_WAIT_MS}. */
+    maxRateLimitWaitMs?: number;
+    /** First backoff for a 429; doubles per attempt. Default {@link RATE_LIMIT_BASE_DELAY_MS}. */
+    rateLimitBaseDelayMs?: number;
+    /**
+     * Cool-down shared across the sweep. Pass ONE instance to every call so a
+     * 429 anywhere holds back everywhere; omit for an isolated request.
+     */
+    gate?: RateLimitGate;
+    /**
+     * Called on every 429 with what npm actually sent and how long we will wait.
+     * The caller decides how loud to be; reporting the FIRST one is enough to
+     * turn "we got throttled" into "npm asked for N seconds" (or into "npm said
+     * nothing, so this delay is ours").
+     */
+    onRateLimit?: (info: {
+        url: string;
+        headers: string;
+        waitMs: number;
+        fromRetryAfter: boolean;
+    }) => void;
+    /**
+     * Called after each state read with what is known SO FAR.
+     *
+     * The probe phase is the silent half of a sweep: 703 packages take minutes
+     * and, until this existed, printed nothing at all between the header and the
+     * plan. The only output in that window was the occasional 2FA prompt, which
+     * makes a working sweep and a wedged one look identical — and the prompt is
+     * the moment a user most needs to know the previous code accomplished
+     * something.
+     */
+    onProgress?: (done: number, total: number, plan: PkgPlan) => void;
     /** Injected delay (tests pass a no-op). Default: real `setTimeout`. */
     sleep?: (ms: number) => Promise<void>;
     /**
@@ -33,6 +65,50 @@ export interface ProbeOptions {
     exists?: (registry: string, name: string) => Promise<boolean | null>;
 }
 export declare 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 declare const RATE_LIMIT_MAX_WAIT_MS = 300000;
+export declare const RATE_LIMIT_BASE_DELAY_MS = 2000;
+/** Ceiling for a single backoff step, so escalation stays legible. */
+export declare const RATE_LIMIT_MAX_STEP_MS = 60000;
+/**
+ * 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 declare function describeRateLimitHeaders(headers: Headers | undefined): string;
+/** Seconds to wait per npm's `Retry-After`, or null when it said nothing usable. */
+export declare function retryAfterMs(headers: Headers | undefined): number | null;
 /**
  * Does the registry serve a packument for this name?
  *
@@ -55,6 +131,47 @@ export declare function packumentExists(registry: string, name: string): Promise
 export declare const DEFAULT_PROBE_CONCURRENCY = 4;
 /** Map a classified trust state to the action the onboard sweep should take. */
 export declare function actionForState(state: TrustState): PkgAction;
+/**
+ * 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 declare class RateLimitGate {
+    private until;
+    private readonly now;
+    private readonly sleeper;
+    constructor(opts?: {
+        now?: () => number;
+        sleep?: (ms: number) => Promise<void>;
+    });
+    /** Block while a cool-down is in effect. */
+    wait(): Promise<void>;
+    /** Hold every request back for at least `ms` from now. */
+    penalize(ms: number): void;
+    /** Milliseconds still owed, for tests and for reporting. */
+    remainingMs(): number;
+}
+/**
+ * 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 declare function requestWaitingOutRateLimit(request: TrustRequester, method: string, url: string, body?: unknown, opts?: ProbeOptions): Promise<TrustRequestResult>;
 /**
  * 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 —

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