@gjsify/cli 0.15.1 → 0.16.1

package/lib/commands/trust.d.ts

@@ -1,4 +1,6 @@
+import { type NpmrcConfig } from '@gjsify/npm-registry';
 import type { Command } from '../types/index.js';
+import { OtpProvider } from '../utils/npm-otp.js';
 import { type TrustEntry } from '../utils/trust-registry.js';
 interface TrustOptions {
     packages?: string[];
@@ -13,4 +15,23 @@ interface TrustOptions {
     'no-private'?: boolean;
 }
 export declare const trustCommand: Command<unknown, TrustOptions>;
+/** Parsed result of a trust-registry request. */
+export interface TrustRequestResult {
+    status: number;
+    json: unknown;
+    text: string;
+}
+/** A `(method, url, body?) => TrustRequestResult` function bound to a registry auth + OTP context. */
+export type TrustRequester = (method: string, url: string, body?: unknown) => Promise<TrustRequestResult>;
+/**
+ * Build a trust-registry requester bound to an npmrc + a shared
+ * {@link OtpProvider}. Each request runs through `withOtpRetry` so a 2FA
+ * challenge reuses the cached code before prompting — the same instance passed
+ * to `createTrustRequester` and to the publish flow shares ONE OTP across a
+ * whole `gjsify onboard` sweep.
+ */
+export declare function createTrustRequester(ctx: {
+    npmrc: NpmrcConfig;
+    otpProvider: OtpProvider;
+}): TrustRequester;
 export type { TrustEntry };

package/lib/commands/trust.js

@@ -21,7 +21,7 @@ import { join } from 'node:path';
 import { DEFAULT_REGISTRY, buildHeaders, registryFor, whoami } from '@gjsify/npm-registry';
 import { discoverWorkspaces, filterWorkspaces } from '@gjsify/workspace';
 import { hasAnyCredential, loadNpmrc } from '../utils/load-npmrc.js';
-import { promptLine } from '../utils/prompt.js';
+import { OtpProvider, withOtpRetry } from '../utils/npm-otp.js';
 import { classifyTrustList, githubTrustBody, normalizeWorkflowFile, parseRepoFromGitRemote, trustUrl, validateRepository, } from '../utils/trust-registry.js';
 export const trustCommand = {
     command: 'trust [packages..]',
@@ -148,63 +148,13 @@ export const trustCommand = {
         if (dryRun)
             console.log('(dry-run — nothing will be written)');
         console.log();
-        // A one-shot OTP supplied via --otp, used on the FIRST challenge then
-        // cleared (a TOTP code is single-use within its ~30s window). After the
-        // first successful OTP the registry opens a ~5-min skip window, so we
-        // do NOT cache + re-send the code — that would re-challenge once it
-        // expires. Instead each request tries WITHOUT an OTP first (the window
-        // covers it) and only prompts when actually challenged. Mirrors npm's
-        // `otplease`.
-        let pendingOtp = args.otp;
-        const request = async (method, url, body) => {
-            const doFetch = async (code) => {
-                const headers = buildHeaders(url, { npmrc });
-                headers['accept'] = 'application/json';
-                if (body !== undefined)
-                    headers['content-type'] = 'application/json';
-                if (code)
-                    headers['npm-otp'] = code;
-                return fetch(url, {
-                    method,
-                    headers,
-                    body: body === undefined ? undefined : JSON.stringify(body),
-                });
-            };
-            // 1) Try without an OTP — succeeds outright (read) or via an active
-            //    2FA-skip window.
-            let res = await doFetch();
-            // 2) On a challenge, use the --otp (once) or prompt, and retry.
-            if (await isOtpChallenge(res)) {
-                let code = pendingOtp;
-                pendingOtp = undefined; // one-shot — never reuse a stale code
-                if (!code) {
-                    code = await promptLine('This operation requires a one-time password.\nEnter OTP: ');
-                }
-                if (!code) {
-                    console.error('gjsify trust: no OTP entered.');
-                    process.exit(1);
-                }
-                res = await doFetch(code);
-                // 3) Still challenged → the code was stale/expired. Prompt fresh once.
-                if (await isOtpChallenge(res)) {
-                    const fresh = await promptLine('OTP rejected (expired?) — enter a fresh code: ');
-                    if (!fresh) {
-                        console.error('gjsify trust: no OTP entered.');
-                        process.exit(1);
-                    }
-                    res = await doFetch(fresh);
-                }
-            }
-            const text = await res.text().catch(() => '');
-            let json = undefined;
-            try {
-                json = text ? JSON.parse(text) : undefined;
-            }
-            catch {
-                /* non-JSON body — leave json undefined */
-            }
-            return { status: res.status, json, text };
-        };
+        // Cache-first OTP across the whole sweep (shared helper). Each request
+        // tries WITHOUT an OTP first (npm's ~5-min 2FA-skip window covers the
+        // packages after the first success) and only sends a code when actually
+        // challenged: the cached `--otp` / last-typed code first, then a fresh
+        // prompt when npm rejects it. See utils/npm-otp.ts.
+        const otpProvider = new OtpProvider(args.otp);
+        const request = createTrustRequester({ npmrc, otpProvider });
         let ok = 0;
         let skipped = 0;
         let unpublished = 0;
@@ -288,18 +238,38 @@ export const trustCommand = {
         }
     },
 };
-/** True when a response is an npm OTP / 2FA challenge. */
-async function isOtpChallenge(res) {
-    if (res.status !== 401)
-        return false;
-    const wwwAuth = (res.headers.get('www-authenticate') ?? '').toLowerCase();
-    if (wwwAuth.includes('otp'))
-        return true;
-    const text = await res
-        .clone()
-        .text()
-        .catch(() => '');
-    return /one-time pass/i.test(text) || /\bEOTP\b/.test(text);
+/**
+ * Build a trust-registry requester bound to an npmrc + a shared
+ * {@link OtpProvider}. Each request runs through `withOtpRetry` so a 2FA
+ * challenge reuses the cached code before prompting — the same instance passed
+ * to `createTrustRequester` and to the publish flow shares ONE OTP across a
+ * whole `gjsify onboard` sweep.
+ */
+export function createTrustRequester(ctx) {
+    return async (method, url, body) => {
+        const doFetch = (code) => {
+            const headers = buildHeaders(url, { npmrc: ctx.npmrc });
+            headers['accept'] = 'application/json';
+            if (body !== undefined)
+                headers['content-type'] = 'application/json';
+            if (code)
+                headers['npm-otp'] = code;
+            const init = { method, headers };
+            if (body !== undefined)
+                init.body = JSON.stringify(body);
+            return fetch(url, init);
+        };
+        const res = await withOtpRetry(doFetch, ctx.otpProvider);
+        const text = await res.text().catch(() => '');
+        let json = undefined;
+        try {
+            json = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            /* non-JSON body — leave json undefined */
+        }
+        return { status: res.status, json, text };
+    };
 }
 function firstLine(s) {
     return s.split('\n')[0].slice(0, 200);

package/lib/commands/workspace.d.ts

@@ -10,4 +10,5 @@ interface WorkspaceCmdOptions {
     cached?: boolean;
 }
 export declare const workspaceCommand: Command<unknown, WorkspaceCmdOptions>;
+export declare function detectPackageManager(): 'yarn' | 'npm' | 'gjsify';
 export {};

package/lib/commands/workspace.js

@@ -19,6 +19,7 @@ import { buildDependencyGraph, discoverWorkspaces, topologicalSort } from '@gjsi
 import { findWorkspaceRoot } from '../utils/workspace-root.js';
 import { BuildCacheRunner, buildCacheEnabledByEnv } from '../utils/build-cache.js';
 import { isGjs } from '@gjsify/rolldown-plugin-gjsify/runtime';
+import { suggestClosest } from '../utils/suggest.js';
 export const workspaceCommand = {
     command: 'workspace <name> <script> [args..]',
     description: 'Run a workspace script (`yarn workspace <name> run <script>` equivalent).',
@@ -76,8 +77,21 @@ export const workspaceCommand = {
         const allWorkspaces = discoverWorkspaces(root);
         const target = allWorkspaces.find((w) => w.name === args.name);
         if (!target) {
-            console.error(`gjsify workspace: no workspace named "${args.name}" — discovered ${allWorkspaces.length} workspace(s)`);
-            process.exit(1);
+            // IMPORTANT: `return process.exit(N)`, not a bare `process.exit(N)`.
+            // Under GJS `process.exit` cannot terminate synchronously (a parked
+            // GLib.MainLoop owns the thread) — it SCHEDULES the exit on a
+            // GLib.idle source and returns a forever-pending Promise. A bare
+            // call therefore falls through to the next statements, dereferences
+            // `target.manifest` on `undefined`, and the resulting throw races
+            // the already-scheduled exit into a SECOND `system.exit` →
+            // `m_should_exit assertion failed` → core dump. `return`-ing halts
+            // the handler so exactly one exit is scheduled. (No-op under Node,
+            // where `process.exit` never returns.)
+            const suggestion = suggestClosest(args.name, allWorkspaces.map((w) => w.name));
+            const hint = suggestion ? ` — did you mean "${suggestion}"?` : '';
+            console.error(`gjsify workspace: no workspace named "${args.name}"${hint} ` +
+                `(discovered ${allWorkspaces.length} workspace(s) under ${root})`);
+            return process.exit(1);
         }
         const runner = detectPackageManager();
         const verbose = args.verbose === true;
@@ -85,8 +99,12 @@ export const workspaceCommand = {
         const continueOnError = args['continue-on-error'] === true;
         const targetScripts = target.manifest.scripts ?? {};
         if (typeof targetScripts[args.script] !== 'string') {
-            console.error(`gjsify workspace: workspace "${args.name}" has no script "${args.script}"`);
-            process.exit(1);
+            const scriptHint = suggestClosest(args.script, Object.keys(targetScripts));
+            console.error(`gjsify workspace: workspace "${args.name}" has no script "${args.script}"` +
+                (scriptHint ? ` — did you mean "${scriptHint}"?` : ''));
+            // `return process.exit` — see the not-found branch above for why a
+            // bare `process.exit` is unsafe under GJS.
+            return process.exit(1);
         }
         // Build the run-list: either just the target, or its transitive
         // workspace-dep closure in topological order followed by the
@@ -136,19 +154,22 @@ export const workspaceCommand = {
                 const e = err instanceof Error ? err : new Error(String(err));
                 console.error(`[${ws.name}] ${e.message}`);
                 if (!continueOnError) {
-                    process.exit(1);
+                    // `return` — a bare `process.exit` would not halt under GJS
+                    // and the loop would keep running the remaining deps.
+                    return process.exit(1);
                 }
                 failures.push({ workspace: ws.name, error: e });
             }
         }
         if (failures.length > 0) {
             console.error(`gjsify workspace: ${failures.length} workspace(s) failed: ${failures.map((f) => f.workspace).join(', ')}`);
-            process.exit(1);
+            return process.exit(1);
         }
         // ensureMainLoop() (called inside spawn) keeps GJS alive after the
         // child exits — without an explicit process.exit() the success path
-        // would park the loop forever.
-        process.exit(0);
+        // would park the loop forever. `return` for symmetry with the error
+        // paths above (see the not-found branch for the GJS rationale).
+        return process.exit(0);
     },
 };
 /**
@@ -232,7 +253,7 @@ async function runOne(ws, script, extraArgs, runner, verbose, cache) {
     if (cache && before)
         cache.storeAfterSuccess(ws, before);
 }
-function detectPackageManager() {
+export function detectPackageManager() {
     // Under GJS there is no Node, so neither `npm` nor `yarn` can run scripts —
     // the only option is `gjsify` itself, resolved via the GJS shim on PATH
     // (see `ensureGjsifyShimOnPath`). This is what makes node-free multi-package

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

@@ -0,0 +1,30 @@
+/**
+ * The literal (non-glob) base directories the build's input source files live
+ * in, derived from the bundler `input` patterns. A file entry maps to its
+ * containing dir, a glob is reduced to the literal prefix before the first
+ * wildcard:
+ *   - `src/index.ts`   → `<cwd>/src`
+ *   - `src/**` + `/*.ts` → `<cwd>/src`
+ *   - `src`            → `<cwd>/src`
+ *
+ * The project root itself is intentionally excluded — a flat library that
+ * keeps its source at the project root and emits there is an explicit layout,
+ * not the `src/`-subdir footgun this guard targets.
+ */
+export declare function inputSourceDirs(input: unknown, cwd: string): string[];
+/**
+ * `true` when writing library output to `outdir` would land build artifacts
+ * inside (or directly on top of) the input source tree. Unsafe iff `outdir`
+ * equals, or is nested under, any input source directory.
+ *
+ *   isOutdirInsideSource('src',      ['<cwd>/src'])       → true   (leak)
+ *   isOutdirInsideSource('src/nest', ['<cwd>/src'])       → true   (leak)
+ *   isOutdirInsideSource('dist/esm', ['<cwd>/src'])       → false  (safe)
+ *   isOutdirInsideSource('lib',      ['<cwd>/src'])       → false  (safe)
+ */
+export declare function isOutdirInsideSource(outdir: string, sourceDirs: readonly string[], cwd: string): boolean;
+/**
+ * The error thrown when a `--library` build would emit into its own source
+ * tree. Names both remedies so the fix is actionable at the point of failure.
+ */
+export declare function libraryOutputLeakError(outdir: string): Error;

package/lib/utils/library-output.js

@@ -0,0 +1,92 @@
+// Guard against the recurring "library build leaks into src/" footgun.
+//
+// `BuildAction.buildLibrary` derives its output directory from
+// `dirname(package.json "module" ?? "main")`. When a package points `main`
+// at its runtime SOURCE entry (`src/index.ts` — the intended entry for
+// Vite/gjsify-compiled consumers, e.g. `@gjsify/adwaita-web`), that derived
+// outdir is `src/`, so `gjsify build --library` writes the compiled `.js`
+// tree straight next to the sources: `src/*.js` / `*2.js` duplicates, a
+// `src/_virtual/` helper dir, and a nested `src/<pkg>/src/**` preserve-modules
+// tree. These pure helpers let the build action refuse that up front instead
+// of silently corrupting the source tree.
+import { dirname, extname, isAbsolute, relative, resolve } from 'node:path';
+/**
+ * The literal (non-glob) base directories the build's input source files live
+ * in, derived from the bundler `input` patterns. A file entry maps to its
+ * containing dir, a glob is reduced to the literal prefix before the first
+ * wildcard:
+ *   - `src/index.ts`   → `<cwd>/src`
+ *   - `src/**` + `/*.ts` → `<cwd>/src`
+ *   - `src`            → `<cwd>/src`
+ *
+ * The project root itself is intentionally excluded — a flat library that
+ * keeps its source at the project root and emits there is an explicit layout,
+ * not the `src/`-subdir footgun this guard targets.
+ */
+export function inputSourceDirs(input, cwd) {
+    const patterns = [];
+    const push = (v) => {
+        if (typeof v === 'string' && v.length > 0)
+            patterns.push(v);
+    };
+    if (typeof input === 'string')
+        push(input);
+    else if (Array.isArray(input))
+        input.forEach(push);
+    else if (input && typeof input === 'object')
+        Object.values(input).forEach(push);
+    const root = resolve(cwd);
+    const dirs = new Set();
+    for (const raw of patterns) {
+        const norm = raw.replace(/\\/g, '/');
+        // Cut the pattern at the first glob metacharacter — everything before
+        // it is a literal path prefix.
+        const globIdx = norm.search(/[*?{}[\]()!+@]/);
+        let base = globIdx === -1 ? norm : norm.slice(0, globIdx);
+        if (globIdx === -1) {
+            // Whole pattern is literal: a file path collapses to its dirname,
+            // a bare directory stays as-is.
+            base = extname(base) ? dirname(base) : base;
+        }
+        else {
+            // The glob cut mid-segment (`src/`, `src/fo*`) — drop the trailing
+            // partial segment so we keep only the complete literal directory.
+            base = base.replace(/\/[^/]*$/, '');
+        }
+        const abs = resolve(root, base || '.');
+        if (abs !== root)
+            dirs.add(abs);
+    }
+    return [...dirs];
+}
+/** `true` when `child` is `parent` itself or nested somewhere under it. */
+function isInsideOrEqual(child, parent) {
+    const rel = relative(parent, child);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+/**
+ * `true` when writing library output to `outdir` would land build artifacts
+ * inside (or directly on top of) the input source tree. Unsafe iff `outdir`
+ * equals, or is nested under, any input source directory.
+ *
+ *   isOutdirInsideSource('src',      ['<cwd>/src'])       → true   (leak)
+ *   isOutdirInsideSource('src/nest', ['<cwd>/src'])       → true   (leak)
+ *   isOutdirInsideSource('dist/esm', ['<cwd>/src'])       → false  (safe)
+ *   isOutdirInsideSource('lib',      ['<cwd>/src'])       → false  (safe)
+ */
+export function isOutdirInsideSource(outdir, sourceDirs, cwd) {
+    const absOut = resolve(cwd, outdir);
+    return sourceDirs.some((dir) => isInsideOrEqual(absOut, dir));
+}
+/**
+ * The error thrown when a `--library` build would emit into its own source
+ * tree. Names both remedies so the fix is actionable at the point of failure.
+ */
+export function libraryOutputLeakError(outdir) {
+    return new Error(`gjsify build --library: refusing to write output into "${outdir}", which holds the ` +
+        `input source — a library build there produces src/*.js duplicates, *2.js, a ` +
+        `_virtual/ helper dir, and a nested preserve-modules tree, silently corrupting the ` +
+        `sources. This output dir was derived from package.json "main"/"module" pointing at ` +
+        `a source path. Fix it by pointing "main"/"module" at the built library (e.g. ` +
+        `lib/index.js) or by passing an explicit --outdir <dir> outside the source tree.`);
+}

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

@@ -0,0 +1,67 @@
+/** A function that prompts the user for one line (an OTP code). */
+export type OtpPromptFn = (question: string) => Promise<string>;
+/**
+ * True when a response is an npm OTP / 2FA challenge (401 + a `www-authenticate`
+ * header naming `otp`, or a body mentioning a one-time password / `EOTP`).
+ * Unifies the detection logic previously inlined in both publish.ts and trust.ts.
+ */
+export declare function isOtpChallenge(res: Response): Promise<boolean>;
+/**
+ * Holds ONE OTP code across a run and knows how to prompt for a fresh one.
+ *
+ * `current()` returns the cached code (seeded from `--otp`, or the last one the
+ * user typed). `refresh()` prompts for a new code and caches it. A single
+ * provider instance shared across many publish + trust operations is what makes
+ * `gjsify onboard` need only one OTP entry for the whole sweep.
+ */
+export declare class OtpProvider {
+    private cached;
+    private readonly promptFn;
+    /**
+     * @param seed     Initial cached code (from `--otp`), or undefined.
+     * @param promptFn How to read a fresh code. Defaults to the TTY-aware
+     *                 `promptLine`. Non-interactive callers pass a function that
+     *                 returns `''` so a challenge surfaces instead of hanging.
+     */
+    constructor(seed?: string, promptFn?: OtpPromptFn);
+    /** The currently cached OTP code, if any. */
+    current(): string | undefined;
+    /**
+     * Prompt for a fresh code, cache it, and return it (the trimmed input, or
+     * `''` when nothing was entered — the caller treats empty as "give up").
+     */
+    refresh(question?: string): Promise<string>;
+}
+export interface OtpRetryOptions {
+    /**
+     * Send the cached code on the FIRST attempt instead of trying without an OTP
+     * first. `gjsify publish --otp <code>` uses this so the PUT carries the
+     * `npm-otp` header immediately (matching npm's `--otp` behaviour). The
+     * cache-first flows (`trust`, `onboard`) leave it false so the first attempt
+     * exploits npm's ~5-min 2FA-skip window and only sends a code when actually
+     * challenged.
+     */
+    seedFirstAttempt?: boolean;
+    /** Max fresh prompts after the cached code is exhausted. Default 2. */
+    maxPrompts?: number;
+    /** Prompt text. Default: the standard npm one-time-password question. */
+    question?: string;
+}
+/**
+ * Run `doFetch` with cache-first OTP retry against a shared {@link OtpProvider}.
+ *
+ * Flow:
+ *   1. First attempt — without an OTP (or WITH the cached code when
+ *      `seedFirstAttempt` is set).
+ *   2. On a 2FA challenge, retry with the currently-cached code (unless step 1
+ *      already sent it).
+ *   3. If still challenged (cache empty/rejected/expired), prompt for a fresh
+ *      code — caching it on the provider so the NEXT operation tries it first —
+ *      and retry, up to `maxPrompts` times.
+ *   4. Return the last response (a challenge the caller must handle) when the
+ *      user declines to enter a code.
+ *
+ * The caller owns the actual fetch + all response interpretation; this only
+ * owns the OTP dance.
+ */
+export declare function withOtpRetry(doFetch: (otp?: string) => Promise<Response>, provider: OtpProvider, opts?: OtpRetryOptions): Promise<Response>;

package/lib/utils/npm-otp.js

@@ -0,0 +1,117 @@
+// Shared npm 2FA / OTP handling for the auth-aware CLI commands
+// (`gjsify publish`, `gjsify trust`, `gjsify onboard`).
+//
+// npm signals "OTP required" via HTTP 401 + a `www-authenticate` header
+// containing `otp` (or, for malformed responses, a body mentioning
+// "one-time pass" / `EOTP`) — see
+// refs/npm-cli/node_modules/npm-registry-fetch/lib/check-response.js.
+//
+// Two pieces were previously duplicated in `publish.ts` and `trust.ts`:
+//   1. detecting the challenge (`isOtpChallenge`);
+//   2. prompting for a code, then retrying the request with it.
+//
+// They are centralised here so a single `OtpProvider` can be injected across
+// MANY operations in one run. `gjsify onboard` sweeps ~110 packages and would
+// otherwise prompt once per package; with one shared provider the user types
+// an OTP once — the cached code is tried first on every subsequent challenge,
+// and a fresh prompt only happens when npm actually rejects/expires it.
+//
+// Standalone `publish`/`trust` keep their existing single-command UX: each
+// still constructs its own provider and prompts on demand.
+import { promptLine } from './prompt.js';
+const DEFAULT_QUESTION = 'This operation requires a one-time password.\nEnter OTP: ';
+/**
+ * True when a response is an npm OTP / 2FA challenge (401 + a `www-authenticate`
+ * header naming `otp`, or a body mentioning a one-time password / `EOTP`).
+ * Unifies the detection logic previously inlined in both publish.ts and trust.ts.
+ */
+export async function isOtpChallenge(res) {
+    if (res.status !== 401)
+        return false;
+    const wwwAuth = (res.headers.get('www-authenticate') ?? '').toLowerCase();
+    if (wwwAuth.includes('otp'))
+        return true;
+    const text = await res
+        .clone()
+        .text()
+        .catch(() => '');
+    return /one-time pass/i.test(text) || /\bEOTP\b/.test(text);
+}
+/**
+ * Holds ONE OTP code across a run and knows how to prompt for a fresh one.
+ *
+ * `current()` returns the cached code (seeded from `--otp`, or the last one the
+ * user typed). `refresh()` prompts for a new code and caches it. A single
+ * provider instance shared across many publish + trust operations is what makes
+ * `gjsify onboard` need only one OTP entry for the whole sweep.
+ */
+export class OtpProvider {
+    cached;
+    promptFn;
+    /**
+     * @param seed     Initial cached code (from `--otp`), or undefined.
+     * @param promptFn How to read a fresh code. Defaults to the TTY-aware
+     *                 `promptLine`. Non-interactive callers pass a function that
+     *                 returns `''` so a challenge surfaces instead of hanging.
+     */
+    constructor(seed, promptFn = promptLine) {
+        this.cached = seed && seed.length > 0 ? seed : undefined;
+        this.promptFn = promptFn;
+    }
+    /** The currently cached OTP code, if any. */
+    current() {
+        return this.cached;
+    }
+    /**
+     * Prompt for a fresh code, cache it, and return it (the trimmed input, or
+     * `''` when nothing was entered — the caller treats empty as "give up").
+     */
+    async refresh(question = DEFAULT_QUESTION) {
+        const code = (await this.promptFn(question)).trim();
+        if (code)
+            this.cached = code;
+        return code;
+    }
+}
+/**
+ * Run `doFetch` with cache-first OTP retry against a shared {@link OtpProvider}.
+ *
+ * Flow:
+ *   1. First attempt — without an OTP (or WITH the cached code when
+ *      `seedFirstAttempt` is set).
+ *   2. On a 2FA challenge, retry with the currently-cached code (unless step 1
+ *      already sent it).
+ *   3. If still challenged (cache empty/rejected/expired), prompt for a fresh
+ *      code — caching it on the provider so the NEXT operation tries it first —
+ *      and retry, up to `maxPrompts` times.
+ *   4. Return the last response (a challenge the caller must handle) when the
+ *      user declines to enter a code.
+ *
+ * The caller owns the actual fetch + all response interpretation; this only
+ * owns the OTP dance.
+ */
+export async function withOtpRetry(doFetch, provider, opts = {}) {
+    const maxPrompts = opts.maxPrompts ?? 2;
+    const question = opts.question ?? DEFAULT_QUESTION;
+    const cached = provider.current();
+    const seededFirst = opts.seedFirstAttempt === true && cached !== undefined;
+    let res = await doFetch(seededFirst ? cached : undefined);
+    if (!(await isOtpChallenge(res)))
+        return res;
+    // Try the cached code if we haven't already sent it.
+    if (!seededFirst && provider.current() !== undefined) {
+        res = await doFetch(provider.current());
+        if (!(await isOtpChallenge(res)))
+            return res;
+    }
+    // Cache empty, rejected, or expired → prompt for a fresh code and retry.
+    for (let i = 0; i < maxPrompts; i++) {
+        const fresh = await provider.refresh(question);
+        if (!fresh)
+            return res; // no input — hand the challenge back to the caller
+        res = await doFetch(fresh);
+        if (!(await isOtpChallenge(res)))
+            return res;
+    }
+    return res;
+}

package/lib/utils/suggest.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Levenshtein edit distance between two strings (classic DP, single-row
+ * rolling buffer). Case-sensitive; callers lower-case first if they want a
+ * case-insensitive match.
+ */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * The closest candidate to `target` by edit distance, or `undefined` when no
+ * candidate is close enough. "Close enough" scales with the target length so
+ * a short name doesn't match everything and a long one tolerates a couple of
+ * typos: `max(2, floor(len/3))`. Comparison is case-insensitive.
+ */
+export declare function suggestClosest(target: string, candidates: readonly string[]): string | undefined;

package/lib/utils/suggest.js

@@ -0,0 +1,51 @@
+// Small "did you mean …?" helper for CLI name typos (unknown workspace,
+// unknown script, …). Pure — no platform imports — so it is unit-testable
+// off any runtime and safe to pull into a GJS-bundled command.
+/**
+ * Levenshtein edit distance between two strings (classic DP, single-row
+ * rolling buffer). Case-sensitive; callers lower-case first if they want a
+ * case-insensitive match.
+ */
+export function editDistance(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    let curr = Array.from({ length: b.length + 1 }, () => 0);
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, // deletion
+            curr[j - 1] + 1, // insertion
+            prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}
+/**
+ * The closest candidate to `target` by edit distance, or `undefined` when no
+ * candidate is close enough. "Close enough" scales with the target length so
+ * a short name doesn't match everything and a long one tolerates a couple of
+ * typos: `max(2, floor(len/3))`. Comparison is case-insensitive.
+ */
+export function suggestClosest(target, candidates) {
+    if (candidates.length === 0)
+        return undefined;
+    const t = target.toLowerCase();
+    const threshold = Math.max(2, Math.floor(target.length / 3));
+    let best;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const d = editDistance(t, candidate.toLowerCase());
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = candidate;
+        }
+    }
+    return best !== undefined && bestDistance <= threshold ? best : undefined;
+}