@gjsify/cli 0.36.0 → 0.37.0

package/lib/utils/normalize-bundler-options.js

@@ -1,24 +1,18 @@
-// One-release deprecation shim: maps the legacy `esbuild?: BuildOptions`
-// field on `.gjsifyrc.js` / `package.json#gjsify` into the equivalent
-// `bundler?: RolldownOptions` shape. Logs a single warning per build.
+// Deprecation shim: maps the legacy `esbuild?: BuildOptions` field on `.gjsifyrc.js` /
+// `package.json#gjsify` into the equivalent `bundler?: RolldownOptions` shape, warning once per
+// build. It was slated for removal in 0.5.0 and is still here at 0.35.0 — the warning text it
+// prints still names 0.5.0, so removing the shim means fixing that string too.
 //
-// Also handles the top-level `bundler.define` alias: Rolldown reads
-// `transform.define`, not a top-level `define`. A user who flat-renames
-// `esbuild: { define: {...} }` → `bundler: { define: {...} }` puts `define`
-// at the top level where Rolldown silently ignores it, causing
-// `ReferenceError: <TOKEN> is not defined` at GJS load time. We auto-map
-// top-level `bundler.define` into `bundler.transform.define` and emit a
-// one-time warning so the user can correct their config.
-//
-// Drop `esbuild` shim in 0.5.0; the `bundler.define` alias is permanent.
+// Also handles the top-level `bundler.define` alias, which is PERMANENT: Rolldown reads
+// `transform.define`, so a user who flat-renames `esbuild: { define }` → `bundler: { define }`
+// lands `define` at the top level where Rolldown silently ignores it, producing
+// `ReferenceError: <TOKEN> is not defined` at GJS load time.
 let warnedOnce = false;
 let warnedDefineOnce = false;
 export function normalizeBundlerOptions(configData) {
     const raw = (configData.bundler ?? {});
-    // --- Top-level bundler.define alias ------------------------------------------
-    // Rolldown only reads `transform.define`; a top-level `define` key is silently
-    // ignored. Detect it, warn once, and move it into `transform.define` so the
-    // user's flat esbuild→bundler rename of `define` Just Works.
+    // Rolldown reads only `transform.define`, so a top-level `define` is moved there (warning
+    // once) rather than being silently ignored — see the header.
     let fromBundler = raw;
     if (typeof raw['define'] === 'object' &&
         raw['define'] !== null) {
@@ -49,11 +43,9 @@ export function normalizeBundlerOptions(configData) {
             "Rename it to 'bundler' (typed as RolldownOptions). See the migration notes in the gjsify CHANGELOG.");
     }
     const fromEsbuild = legacyEsbuildToRolldown(configData.esbuild);
-    // Plain user-config merge — we deliberately do NOT call
-    // `mergeBundlerOptions` here, because that function strips `input` and
-    // `external` from its overrides arg (it assumes the *orchestrator* is
-    // the override source and the user the base). Here both inputs are
-    // user-provided config and `input` must survive the merge.
+    // Deliberately NOT `mergeBundlerOptions`: that strips `input`/`external` from its overrides
+    // arg because it assumes the ORCHESTRATOR is the override source. Here both sides are user
+    // config, and `input` must survive the merge.
     const out = { ...fromEsbuild, ...fromBundler };
     if (fromEsbuild.output || fromBundler.output) {
         out.output = { ...fromEsbuild.output, ...fromBundler.output };
@@ -111,33 +103,23 @@ function legacyEsbuildToRolldown(esb) {
         out.transform = transform;
     if (Object.keys(resolve).length > 0)
         out.resolve = resolve;
-    // Discarded (handled elsewhere):
-    //   esb.inject  — esbuild's array-of-side-effect-files; surfaced at the
-    //                 CLI layer instead, via input expansion.
-    //   esb.loader  — replaced by top-level `gjsify.loaders` (see ConfigData);
-    //                 migration: `esbuild.loader: { '.png': 'dataurl', '.glsl': 'text' }`
-    //                 → `loaders: { '.png': 'dataurl', '.glsl': 'text' }`.
+    // Discarded, handled elsewhere: `esb.inject` (surfaced at the CLI layer via input
+    // expansion) and `esb.loader` (replaced by top-level `gjsify.loaders`, see ConfigData).
     return out;
 }
 /**
- * Shallow merge with deep-merge of `output`, `transform`, and `resolve`. The
- * second argument wins on conflicts, matching `merge(target, ...sources)`
- * semantics from `@gjsify/rolldown-plugin-gjsify/utils/merge`.
- *
- * `base` is typically the Rolldown-generic shape returned by the orchestrator;
- * `overrides` is the user's `BundlerOptions` from `.gjsifyrc.js` plus CLI
- * flag merges. Single-output assumption matches `BundlerOptions['output']`.
+ * Shallow merge with deep-merge of `output`, `transform` and `resolve`; `overrides` wins,
+ * matching `merge(target, ...sources)` from `@gjsify/rolldown-plugin-gjsify/utils/merge`. `base`
+ * is the orchestrator's Rolldown-generic shape, `overrides` the user's config plus CLI flags.
  *
- * The orchestrator-side `input` is authoritative — it's the post-glob-expansion
- * value. Overriding it with the user's raw glob string would re-introduce
- * unresolved glob patterns into the final Rolldown call. Same for `external`,
- * which the orchestrator concatenates with platform defaults already.
+ * The orchestrator's `input` is authoritative because it is the post-glob-expansion value —
+ * taking the user's raw glob string would re-introduce unresolved patterns into the Rolldown
+ * call. Same for `external`, which the orchestrator has already concatenated with the platform
+ * defaults.
  */
 export function mergeBundlerOptions(base, overrides) {
-    // Strip fields the orchestrator owns authoritatively — the user has
-    // already had their say via the orchestrator's `userExternal` / input
-    // expansion; merging the raw values back on top would clobber the
-    // post-processing.
+    // Strip the fields the orchestrator owns: the user already had their say through
+    // `userExternal` / input expansion, and merging the raw values back would clobber it.
     const { input: _ignoredInput, external: _ignoredExternal, ...overridesRest } = overrides;
     const out = { ...base, ...overridesRest };
     if (base.output || overrides.output) {

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

@@ -6,14 +6,12 @@ interface OidcExchangeOptions {
     /** Optional verbose logger — receives single-line strings. */
     log?: (msg: string) => void;
     /**
-     * Max retries on a TRANSIENT exchange failure (5xx / 429 / network error).
-     * Default 3. A transient npm-side blip (e.g. a 503 Service Unavailable on a
-     * single package mid-release) used to fall straight through to token auth,
-     * which in OIDC-only CI has no token → a 404 that broke the release while
-     * the workflow stayed green (the `@gjsify/process@0.7.3` v0.7.3 incident).
-     * Retrying the exchange keeps the publish on the OIDC path. Non-transient
-     * statuses (404 "package not found", 401/403 misconfig) are NOT retried —
-     * they're surfaced immediately so `--tolerate-untrusted-new` etc. still work.
+     * Max retries on a TRANSIENT exchange failure (5xx / 429 / network error), default 3. A
+     * single npm-side 503 mid-release used to fall straight through to token auth, which in
+     * OIDC-only CI has no token → a 404 that broke the release while the workflow stayed green
+     * (hit on `@gjsify/process` during v0.7.3). Retrying keeps the publish on the OIDC path.
+     * Non-transient statuses (404 "package not found", 401/403 misconfig) are NOT retried, so
+     * `--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. */
@@ -34,55 +32,43 @@ export declare class OidcExchangeError extends Error {
     readonly body: string;
     readonly packageName: string;
     /**
-     * The non-secret claims decoded from the GitHub OIDC JWT that npm
-     * rejected — `repository`, `workflow_ref`, `environment`, … These are
-     * exactly what npm matches a Trusted Publisher config against, so on a
-     * 401/403 they tell you precisely which fields the config must carry.
+     * Non-secret claims decoded from the rejected JWT (`repository`, `workflow_ref`,
+     * `environment`, …) — exactly what npm matches a Trusted Publisher config against, so on
+     * a 401/403 they name which fields the config must carry.
      */
     readonly claims?: Record<string, unknown> | undefined;
     constructor(message: string, status: number, body: string, packageName: string, 
     /**
-     * The non-secret claims decoded from the GitHub OIDC JWT that npm
-     * rejected — `repository`, `workflow_ref`, `environment`, … These are
-     * exactly what npm matches a Trusted Publisher config against, so on a
-     * 401/403 they tell you precisely which fields the config must carry.
+     * Non-secret claims decoded from the rejected JWT (`repository`, `workflow_ref`,
+     * `environment`, …) — exactly what npm matches a Trusted Publisher config against, so on
+     * a 401/403 they name which fields the config must carry.
      */
     claims?: Record<string, unknown> | undefined);
 }
 /**
- * Decode the (non-secret) payload of a JWT — the middle base64url segment.
- * A GitHub OIDC id-token's payload is public metadata about the workflow run
- * (`repository`, `repository_owner`, `workflow_ref`, `job_workflow_ref`,
- * `ref`, `environment`, `sub`, …); the SIGNATURE is what makes it trustworthy.
- * Returns null if the token isn't a well-formed three-part JWT.
+ * Decode the non-secret payload of a JWT — the middle base64url segment. A GitHub OIDC
+ * id-token's payload is public metadata about the workflow run; the SIGNATURE is what makes it
+ * trustworthy. Null when the token isn't a well-formed three-part JWT.
  */
 export declare function decodeJwtPayload(jwt: string): Record<string, unknown> | null;
 /**
- * Probe whether OIDC publishing is available in the current process —
- * cheap env-var check, no network access. Used by `gjsify publish` to
- * decide between OIDC and token-based auth in auto-detect mode.
+ * Whether OIDC publishing is available in this process — a cheap env-var check with no network
+ * access, used by `gjsify publish` to choose between OIDC and token auth in auto-detect mode.
  */
 export declare function hasGithubOidcEnv(): boolean;
 /**
- * Request a GitHub Actions OIDC ID token for the given audience.
- * Throws `OidcUnavailableError` when the required env vars are missing
- * (caller can fall back to token auth) or when GitHub rejects the request.
+ * Request a GitHub Actions OIDC ID token for `audience`. Throws `OidcUnavailableError` when the
+ * env vars are missing (the caller can fall back to token auth) or GitHub rejects the request.
  */
 export declare function fetchGithubOidcToken(audience: string, log?: (msg: string) => void): Promise<string>;
 /**
- * Exchange a GitHub OIDC JWT for a short-lived npm publish token at
- * `/-/npm/v1/oidc/token/exchange/package/<escaped-name>`. The npm
- * registry validates the JWT against the package's Trusted Publisher
- * config — if no Trusted Publisher is configured, or the JWT comes from
- * a repo/workflow that doesn't match, the exchange returns a 4xx with
- * a descriptive body which we propagate as `OidcExchangeError`.
+ * Exchange a GitHub OIDC JWT for a short-lived npm publish token. A missing or non-matching
+ * Trusted Publisher config comes back as a 4xx with a descriptive body, propagated as
+ * `OidcExchangeError`.
  */
 export declare function exchangeOidcForNpmToken(args: OidcExchangeOptions & {
     idToken: string;
 }): Promise<string>;
-/**
- * End-to-end: probe env → fetch id-token → exchange for npm token.
- * One-shot convenience for `gjsify publish` and the verification command.
- */
+/** End-to-end: probe env → fetch id-token → exchange for an npm token. */
 export declare function getNpmTrustedToken(opts: OidcExchangeOptions): Promise<OidcExchangeResult>;
 export {};

package/lib/utils/npm-oidc.js

@@ -2,20 +2,14 @@
 //
 // Two-step flow, mirroring `refs/npm-cli/lib/utils/oidc.js`:
 //
-//   1. Request a GitHub Actions OIDC ID token (JWT) from the runner.
-//      Requires `permissions: id-token: write` in the calling workflow.
-//      GitHub provides `ACTIONS_ID_TOKEN_REQUEST_URL` and
-//      `ACTIONS_ID_TOKEN_REQUEST_TOKEN` env vars; we GET the URL with
-//      the runner-provided audience (`npm:registry.npmjs.org`).
+//   1. GET a GitHub Actions OIDC ID token (JWT) from the runner, at
+//      `ACTIONS_ID_TOKEN_REQUEST_URL` with the audience `npm:registry.npmjs.org`. Requires
+//      `permissions: id-token: write` in the calling workflow.
+//   2. Exchange that JWT at `/-/npm/v1/oidc/token/exchange/package/<name>` for a short-lived
+//      (~5 min) npm publish token; npm verifies it against the package's Trusted Publisher
+//      (repository + workflow filename + optional environment).
 //
-//   2. Exchange that JWT at npm's `/-/npm/v1/oidc/token/exchange/package/<name>`
-//      endpoint for a short-lived (~5 min) npm publish token. npm verifies
-//      the JWT against the package's configured Trusted Publisher
-//      (repository + workflow filename + optional environment) and either
-//      issues a token or rejects with an explanatory error.
-//
-// The token returned by step 2 is used for the publish PUT in the same
-// way the long-lived NPM_TOKEN would have been — drop-in replacement.
+// The resulting token is a drop-in replacement for a long-lived NPM_TOKEN on the publish PUT.
 //
 // Reference: refs/npm-cli/lib/utils/oidc.js
 // Original: Copyright (c) npm contributors. Artistic-2.0.
@@ -37,10 +31,9 @@ export class OidcExchangeError extends Error {
     claims;
     constructor(message, status, body, packageName, 
     /**
-     * The non-secret claims decoded from the GitHub OIDC JWT that npm
-     * rejected — `repository`, `workflow_ref`, `environment`, … These are
-     * exactly what npm matches a Trusted Publisher config against, so on a
-     * 401/403 they tell you precisely which fields the config must carry.
+     * Non-secret claims decoded from the rejected JWT (`repository`, `workflow_ref`,
+     * `environment`, …) — exactly what npm matches a Trusted Publisher config against, so on
+     * a 401/403 they name which fields the config must carry.
      */
     claims) {
         super(message);
@@ -52,11 +45,9 @@ export class OidcExchangeError extends Error {
     }
 }
 /**
- * Decode the (non-secret) payload of a JWT — the middle base64url segment.
- * A GitHub OIDC id-token's payload is public metadata about the workflow run
- * (`repository`, `repository_owner`, `workflow_ref`, `job_workflow_ref`,
- * `ref`, `environment`, `sub`, …); the SIGNATURE is what makes it trustworthy.
- * Returns null if the token isn't a well-formed three-part JWT.
+ * Decode the non-secret payload of a JWT — the middle base64url segment. A GitHub OIDC
+ * id-token's payload is public metadata about the workflow run; the SIGNATURE is what makes it
+ * trustworthy. Null when the token isn't a well-formed three-part JWT.
  */
 export function decodeJwtPayload(jwt) {
     const parts = jwt.split('.');
@@ -72,17 +63,15 @@ export function decodeJwtPayload(jwt) {
     }
 }
 /**
- * Probe whether OIDC publishing is available in the current process —
- * cheap env-var check, no network access. Used by `gjsify publish` to
- * decide between OIDC and token-based auth in auto-detect mode.
+ * Whether OIDC publishing is available in this process — a cheap env-var check with no network
+ * access, used by `gjsify publish` to choose between OIDC and token auth in auto-detect mode.
  */
 export function hasGithubOidcEnv() {
     return Boolean(process.env.ACTIONS_ID_TOKEN_REQUEST_URL && process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN);
 }
 /**
- * Request a GitHub Actions OIDC ID token for the given audience.
- * Throws `OidcUnavailableError` when the required env vars are missing
- * (caller can fall back to token auth) or when GitHub rejects the request.
+ * Request a GitHub Actions OIDC ID token for `audience`. Throws `OidcUnavailableError` when the
+ * env vars are missing (the caller can fall back to token auth) or GitHub rejects the request.
  */
 export async function fetchGithubOidcToken(audience, log) {
     const url = process.env.ACTIONS_ID_TOKEN_REQUEST_URL;
@@ -91,15 +80,11 @@ export async function fetchGithubOidcToken(audience, log) {
         throw new OidcUnavailableError('GitHub Actions OIDC env vars (ACTIONS_ID_TOKEN_REQUEST_{URL,TOKEN}) not set. ' +
             'The calling workflow needs `permissions: id-token: write`.', 'no-env');
     }
-    // Append the audience by STRING CONCATENATION, mirroring @actions/core's
-    // getIDToken (`${runtimeUrl}&audience=${encodeURIComponent(aud)}`) and the
-    // raw-curl probe that returns HTTP 201. Do NOT use `URL.searchParams.set` +
-    // `.href`: under GJS that serialization dropped the `audience` query param,
-    // so GitHub issued an id-token with the DEFAULT audience (the repo API URL)
-    // instead of `npm:registry.npmjs.org`. npm then rejected the otherwise-valid
-    // token with 401 "unauthorized" — the JWT's repository/workflow_ref/sub
-    // claims all matched the Trusted Publisher, only `aud` was wrong, which is
-    // exactly the failure we saw (curl from the same workflow → 201).
+    // Append the audience by STRING CONCATENATION, as @actions/core's getIDToken does. Do NOT
+    // use `URL.searchParams.set` + `.href`: under GJS that serialization dropped the `audience`
+    // param, so GitHub issued an id-token with the DEFAULT audience (the repo API URL) and npm
+    // rejected an otherwise-valid token with 401 — repository/workflow_ref/sub all matched the
+    // Trusted Publisher, only `aud` was wrong.
     const sep = url.includes('?') ? '&' : '?';
     const requestUrl = `${url}${sep}audience=${encodeURIComponent(audience)}`;
     log?.(`gjsify oidc: GET ${requestUrl.replace(bearer, '<bearer>')}`);
@@ -121,12 +106,9 @@ export async function fetchGithubOidcToken(audience, log) {
     return json.value;
 }
 /**
- * Exchange a GitHub OIDC JWT for a short-lived npm publish token at
- * `/-/npm/v1/oidc/token/exchange/package/<escaped-name>`. The npm
- * registry validates the JWT against the package's Trusted Publisher
- * config — if no Trusted Publisher is configured, or the JWT comes from
- * a repo/workflow that doesn't match, the exchange returns a 4xx with
- * a descriptive body which we propagate as `OidcExchangeError`.
+ * Exchange a GitHub OIDC JWT for a short-lived npm publish token. A missing or non-matching
+ * Trusted Publisher config comes back as a 4xx with a descriptive body, propagated as
+ * `OidcExchangeError`.
  */
 export async function exchangeOidcForNpmToken(args) {
     const { packageName, registry, idToken, log } = args;
@@ -154,8 +136,7 @@ export async function exchangeOidcForNpmToken(args) {
                     'Content-Type': 'application/json',
                     Accept: 'application/json',
                 },
-                // npm's exchange endpoint accepts an empty JSON body — the JWT
-                // is the proof, no additional claims needed from us.
+                // Empty JSON body: the JWT is the proof, no additional claims are needed.
                 body: '{}',
             });
         }
@@ -171,10 +152,7 @@ export async function exchangeOidcForNpmToken(args) {
         }
         const text = await res.text().catch(() => '');
         if (!res.ok) {
-            // Retry only TRANSIENT npm-side failures; surface everything else
-            // (404/401/403 etc.) immediately so the caller's diagnostics —
-            // `--tolerate-untrusted-new`, Trusted-Publisher misconfig hints —
-            // still fire on the first response.
+            // 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);
                 log?.(`gjsify oidc: transient ${res.status} ${res.statusText} for ${packageName} (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms`);
@@ -196,10 +174,7 @@ export async function exchangeOidcForNpmToken(args) {
         return json.token;
     }
 }
-/**
- * End-to-end: probe env → fetch id-token → exchange for npm token.
- * One-shot convenience for `gjsify publish` and the verification command.
- */
+/** End-to-end: probe env → fetch id-token → exchange for an npm token. */
 export async function getNpmTrustedToken(opts) {
     const audience = `npm:${new URL(opts.registry).hostname}`;
     const idToken = await fetchGithubOidcToken(audience, opts.log);

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

@@ -14,13 +14,13 @@ export interface OtpCacheOptions {
 /** `true` unless `GJSIFY_NO_OTP_CACHE` is set to a truthy value. */
 export declare function isOtpCacheEnabled(): boolean;
 /**
- * Read the cached code for `registry`, or `undefined` on a miss / expiry /
- * opt-out. An EXPIRED entry is deleted as a side effect.
+ * The cached code for `registry`, or `undefined` on a miss / expiry / opt-out. An EXPIRED entry
+ * is deleted as a side effect.
  */
 export declare function readCachedOtp(registry: string, opts?: OtpCacheOptions): string | undefined;
 /**
- * Persist `otp` for `registry` with a fresh TTL, perms 0600. No-op on opt-out
- * or empty code. Best-effort — a write failure never throws.
+ * Persist `otp` for `registry` with a fresh TTL, perms 0600. No-op on opt-out or an empty code;
+ * a write failure never throws.
  */
 export declare function writeCachedOtp(registry: string, otp: string, opts?: OtpCacheOptions): void;
 /** Drop the cached code for a single registry (invalid/consumed OTP, or logout). */

package/lib/utils/npm-otp-cache.js

@@ -1,22 +1,17 @@
 // Short-lived, CROSS-INVOCATION cache for the npm 2FA one-time code.
 //
-// A TOTP stays valid for its ~30 s window, so a `login → onboard → publish →
-// trust` sequence of SEPARATE `gjsify` processes should reuse ONE typed code
-// instead of prompting per command. The in-process `OtpProvider` cache
-// (utils/npm-otp.ts) only survives a single command; this file is the layer
-// under it that survives across invocations.
+// A TOTP stays valid for its ~30 s window, so a `login → onboard → publish → trust` sequence of
+// SEPARATE `gjsify` processes should reuse ONE typed code instead of prompting per command. The
+// in-process `OtpProvider` cache (utils/npm-otp.ts) survives only a single command; this is the
+// layer under it that survives across invocations.
 //
-// Design:
-//   - Stored in a temp file (under `$XDG_RUNTIME_DIR`, else the OS temp dir —
-//     NEVER the repo), perms 0600, with a stamped absolute `expiresAt`.
-//   - TTL = one TOTP window (30 s), deliberately short. A read past the expiry
-//     ignores AND deletes the file.
-//   - Keyed by the REGISTRY URL, so a code for one registry is never replayed
-//     against another.
-//   - Best-effort: a cache miss/error NEVER breaks the command — a stale or
-//     unreadable entry degrades to "no cached code" (re-prompt).
-//   - Opt-out: `GJSIFY_NO_OTP_CACHE=1` disables it entirely; `gjsify logout`
-//     clears it.
+//   - A temp file under `$XDG_RUNTIME_DIR`, else the OS temp dir — NEVER the repo — perms 0600,
+//     with a stamped absolute `expiresAt`.
+//   - TTL = one TOTP window (30 s), deliberately short; a read past expiry ignores AND deletes.
+//   - Keyed by REGISTRY URL, so a code for one registry is never replayed against another.
+//   - Best-effort: a stale or unreadable entry degrades to "no cached code" (re-prompt), never
+//     an error.
+//   - `GJSIFY_NO_OTP_CACHE=1` disables it entirely; `gjsify logout` clears it.
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -50,8 +45,8 @@ function cacheFileFor(registry, opts) {
     return join(cacheBaseDir(opts), `otp-${safe || 'default'}.json`);
 }
 /**
- * Read the cached code for `registry`, or `undefined` on a miss / expiry /
- * opt-out. An EXPIRED entry is deleted as a side effect.
+ * The cached code for `registry`, or `undefined` on a miss / expiry / opt-out. An EXPIRED entry
+ * is deleted as a side effect.
  */
 export function readCachedOtp(registry, opts) {
     if (!isOtpCacheEnabled())
@@ -70,7 +65,7 @@ export function readCachedOtp(registry, opts) {
         if (entry.registry !== normalizeRegistry(registry))
             return undefined;
         if (now >= entry.expiresAt) {
-            deleteCacheFile(file); // expired → ignore + delete
+            deleteCacheFile(file);
             return undefined;
         }
         return entry.otp.length > 0 ? entry.otp : undefined;
@@ -82,8 +77,8 @@ export function readCachedOtp(registry, opts) {
     }
 }
 /**
- * Persist `otp` for `registry` with a fresh TTL, perms 0600. No-op on opt-out
- * or empty code. Best-effort — a write failure never throws.
+ * Persist `otp` for `registry` with a fresh TTL, perms 0600. No-op on opt-out or an empty code;
+ * a write failure never throws.
  */
 export function writeCachedOtp(registry, otp, opts) {
     if (!isOtpCacheEnabled())
@@ -98,8 +93,8 @@ export function writeCachedOtp(registry, otp, opts) {
         const file = cacheFileFor(registry, opts);
         const entry = { otp, expiresAt: now + ttl, registry: normalizeRegistry(registry) };
         writeFileSync(file, JSON.stringify(entry), { mode: 0o600 });
-        // Enforce 0600 even when the file pre-existed with looser perms (writeFile
-        // only applies `mode` on create) — the code is a live secret.
+        // Enforce 0600 even when the file pre-existed with looser perms — `writeFileSync` applies
+        // `mode` only on create, and the code is a live secret.
         chmodSync(file, 0o600);
     }
     catch {
@@ -116,7 +111,7 @@ export function clearAllCachedOtp(opts) {
         rmSync(cacheBaseDir(opts), { recursive: true, force: true });
     }
     catch {
-        /* ignore */
+        /* best-effort — an unremovable cache dir must not fail a logout */
     }
 }
 /** POSIX file-mode bits of the cache file (test helper); `undefined` if absent. */
@@ -137,6 +132,6 @@ function deleteCacheFile(file) {
             rmSync(file, { force: true });
     }
     catch {
-        /* ignore */
+        /* best-effort — the entry has already been treated as a miss by every caller */
     }
 }

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

@@ -3,7 +3,6 @@ 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>;
 /** Options controlling the cross-invocation file cache an {@link OtpProvider} rides on top of. */
@@ -12,9 +11,9 @@ export interface OtpProviderOptions {
      * Registry URL scoping the SHORT-LIVED cross-invocation OTP cache
      * (`utils/npm-otp-cache.ts`). When set, a provider constructed WITHOUT an
      * explicit seed reads the file-cached code first (so a sibling `gjsify`
-     * command's typed OTP is reused within its ~30 s TOTP window), and every
-     * newly typed/seeded code is written back for the next command. Omit → the
-     * provider is in-process-only (the historical behaviour).
+     * command's typed OTP is reused within its ~30 s TOTP window), and every newly
+     * typed/seeded code is written back for the next command. Omit for an
+     * in-process-only provider.
      */
     registry?: string;
 }
@@ -22,12 +21,11 @@ export interface OtpProviderOptions {
  * Holds ONE OTP code across a run and knows how to prompt for a fresh one.
  *
  * `current()` returns the cached code (seeded from `--otp`, the cross-invocation
- * file cache, or the last one the user typed). `refresh()` prompts for a new
- * code and caches it (in-process AND — when a `registry` is set — in the
- * short-lived file cache). A single provider instance shared across many
- * publish + trust operations is what makes `gjsify onboard` need only one OTP
- * entry for the whole sweep; the file cache extends that reuse across SEPARATE
- * `gjsify` invocations (`login → onboard → publish → trust`).
+ * file cache, or the last one typed); `refresh()` prompts for a new one and caches
+ * it in-process AND — when a `registry` is set — in the short-lived file cache. One
+ * shared instance is what makes `gjsify onboard` need a single OTP entry for a whole
+ * sweep; the file cache extends that reuse across SEPARATE invocations
+ * (`login → onboard → publish → trust`).
  */
 export declare class OtpProvider {
     private cached;
@@ -44,15 +42,14 @@ export declare class OtpProvider {
     /** The currently cached OTP code, if any. */
     current(): string | undefined;
     /**
-     * Prompt for a fresh code, cache it (in-process + file cache), and return
-     * it (the trimmed input, or `''` when nothing was entered — the caller
-     * treats empty as "give up").
+     * Prompt for a fresh code, cache it (in-process + file cache), and return the
+     * trimmed input — `''` when nothing was entered, which callers read as "give up".
      */
     refresh(question?: string): Promise<string>;
     /**
-     * Drop the cached code (in-process AND the cross-invocation file entry)
-     * after npm rejects it as invalid/consumed — so the NEXT command re-prompts
-     * instead of replaying a single-use code that the registry already burned.
+     * Drop the cached code (in-process AND the cross-invocation file entry) after npm
+     * rejects it, so the NEXT command re-prompts instead of replaying a single-use
+     * code the registry already burned.
      */
     invalidate(): void;
 }
@@ -72,20 +69,13 @@ export interface OtpRetryOptions {
     question?: string;
 }
 /**
- * Run `doFetch` with cache-first OTP retry against a shared {@link OtpProvider}.
+ * Run `doFetch` with cache-first OTP retry against a shared {@link OtpProvider}:
+ * attempt without an OTP (or with the cached code under `seedFirstAttempt`), retry
+ * with the cached code on a challenge, then prompt for fresh codes up to
+ * `maxPrompts` times. A declined prompt returns the last challenge response for the
+ * caller to handle.
  *
- * 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.
+ * The caller owns the fetch and all response interpretation; this owns only the OTP
+ * dance.
  */
 export declare function withOtpRetry(doFetch: (otp?: string) => Promise<Response>, provider: OtpProvider, opts?: OtpRetryOptions): Promise<Response>;