@gjsify/cli 0.4.34 → 0.4.36

package/lib/utils/install-backend-native.js

@@ -19,6 +19,7 @@ import * as os from 'node:os';
 import { Range, SemVer, maxSatisfying, satisfies } from '@gjsify/semver';
 import { DEFAULT_REGISTRY, fetchPackument, fetchTarball, parseNpmrc, } from '@gjsify/npm-registry';
 import { extractTarball } from '@gjsify/tar';
+import { getCachedTarball, putCachedTarball, } from './install-tarball-cache.js';
 const DEFAULT_CONCURRENCY = Number(process.env.GJSIFY_INSTALL_CONCURRENCY ?? '8') || 8;
 const LOCKFILE_NAME = 'gjsify-lock.json';
 const LOCKFILE_VERSION = 2;
@@ -29,6 +30,7 @@ export async function installPackagesNative(opts) {
     fs.mkdirSync(opts.prefix, { recursive: true });
     const npmrc = await loadNpmrc(opts);
     const log = makeLogger(opts.verbose ?? false);
+    const progress = opts.progress;
     const lockfilePath = path.join(opts.prefix, LOCKFILE_NAME);
     const existingLock = readLockfile(lockfilePath);
     let nodes;
@@ -56,14 +58,14 @@ export async function installPackagesNative(opts) {
     }
     else {
         log('install: resolving %d top-level spec(s) → %s', opts.specs.length, opts.prefix);
-        nodes = await resolveDeps(opts.specs, npmrc, log, opts.overrides, opts.skipDeps);
+        nodes = await resolveDeps(opts.specs, npmrc, log, opts.overrides, opts.skipDeps, opts.signal, progress);
         if (opts.lockfile) {
             writeLockfile(lockfilePath, opts.specs, nodes);
             log('install: wrote %s (%d entries)', LOCKFILE_NAME, nodes.length);
         }
     }
     log('install: downloading %d tarball(s)', nodes.length);
-    await downloadAndExtractAll(nodes, opts.prefix, npmrc, log);
+    await downloadAndExtractAll(nodes, opts.prefix, npmrc, log, opts.signal, progress);
     await linkBins(nodes, opts.prefix, log);
     log('install: done');
     // Surface the top-level requested packages so callers can update
@@ -119,7 +121,8 @@ function parseSpecName(spec) {
  * the root. Each placement returns a `ResolvedNode` whose `installPath`
  * captures where it lives in the tree.
  */
-async function resolveDeps(specs, npmrc, log, overrides, skipDeps) {
+async function resolveDeps(specs, npmrc, log, overrides, skipDeps, signal, progress) {
+    progress?.beginPhase('resolve', specs.length);
     const applyOverride = (name, range) => {
         if (!overrides)
             return range;
@@ -138,6 +141,7 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps) {
             return cached;
         const fresh = fetchPackument(name, {
             npmrc,
+            signal,
             onRetry: ({ attempt, error, delayMs }) => {
                 log('packument %s: retry %d after %dms (%s)', name, attempt, delayMs, errMsg(error));
             },
@@ -201,6 +205,16 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps) {
                 root.set(edge.name, node);
             }
             log('resolve: %s@%s ← %s (at %s)', edge.name, version, edge.range, installPath);
+            // Soft-total tracks the dep graph as it grows. We use
+            // byPath.size (resolved so far) + queue.length (still to
+            // process) as a moving estimate that converges as work
+            // finishes — yarn/pnpm use the same pattern.
+            progress?.update({
+                phase: 'resolve',
+                current: byPath.size,
+                total: byPath.size + queue.length,
+                name: `${edge.name}@${version}`,
+            });
             if (!skipDeps) {
                 for (const [depName, depRange] of Object.entries(node.dependencies)) {
                     queue.push({
@@ -230,6 +244,7 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps) {
             throw e;
         }
     }
+    progress?.endPhase('resolve');
     return Array.from(byPath.values());
 }
 /**
@@ -448,13 +463,24 @@ export function pickVersion(packument, range) {
     });
     return maxSatisfying(versions, parsedRange);
 }
-async function downloadAndExtractAll(nodes, prefix, npmrc, log) {
+async function downloadAndExtractAll(nodes, prefix, npmrc, log, signal, progress) {
     // Sort by install-path depth ascending so parents extract before
     // children. Extracting a parent on top of an existing child would
     // wipe out the child.
     const queue = [...nodes].sort((a, b) => depth(a.installPath) - depth(b.installPath) || (a.installPath < b.installPath ? -1 : 1));
     const workers = [];
     const concurrency = Math.max(1, Math.min(DEFAULT_CONCURRENCY, queue.length));
+    progress?.beginPhase('download', queue.length);
+    let completed = 0;
+    const tickProgress = (node) => {
+        completed++;
+        progress?.update({
+            phase: 'download',
+            current: completed,
+            total: queue.length,
+            name: `${node.name}@${node.version}`,
+        });
+    };
     // Parents (depth 1) are extracted serially first to avoid concurrent
     // `rm -rf` + extract races with their children. Once depth-1 is done,
     // depths >=2 run with full concurrency.
@@ -466,7 +492,8 @@ async function downloadAndExtractAll(nodes, prefix, npmrc, log) {
         const node = queue[cursor++];
         if (!node)
             break;
-        await extractOne(node, prefix, npmrc, log);
+        await extractOne(node, prefix, npmrc, log, signal);
+        tickProgress(node);
     }
     // Concurrent nested pass.
     for (let i = 0; i < concurrency; i++) {
@@ -478,13 +505,15 @@ async function downloadAndExtractAll(nodes, prefix, npmrc, log) {
                 const node = queue[idx];
                 if (!node)
                     return;
-                await extractOne(node, prefix, npmrc, log);
+                await extractOne(node, prefix, npmrc, log, signal);
+                tickProgress(node);
             }
         })());
     }
     await Promise.all(workers);
+    progress?.endPhase('download');
 }
-async function extractOne(node, prefix, npmrc, log) {
+async function extractOne(node, prefix, npmrc, log, signal) {
     const dest = path.join(prefix, node.installPath);
     // Defense-in-depth against the workspace-source-wipe data-loss bug:
     // every extractable node MUST land inside a `node_modules/` directory.
@@ -495,14 +524,28 @@ async function extractOne(node, prefix, npmrc, log) {
     // source dir — the realpath check additionally rejects a `dest` that
     // resolves THROUGH a symlink into a directory outside node_modules.
     assertNodeModulesDest(dest, node);
-    log('fetch: %s@%s ← %s (→ %s)', node.name, node.version, node.tarballUrl, node.installPath);
-    const bytes = await fetchTarball(node.tarballUrl, {
-        npmrc,
-        integrity: node.integrity,
-        onRetry: ({ attempt, error, delayMs }) => {
-            log('tarball %s@%s: retry %d after %dms (%s)', node.name, node.version, attempt, delayMs, errMsg(error));
-        },
-    });
+    // Hit the content-addressable cache before touching the network.
+    // Tarballs are immutable per SRI integrity, so a hash hit means the
+    // cached bytes are byte-identical to whatever the registry would
+    // return — no need to verify by re-download.
+    let bytes = getCachedTarball(node.integrity);
+    if (bytes) {
+        log('cache-hit: %s@%s ← %s', node.name, node.version, node.integrity);
+    }
+    else {
+        log('fetch: %s@%s ← %s (→ %s)', node.name, node.version, node.tarballUrl, node.installPath);
+        bytes = await fetchTarball(node.tarballUrl, {
+            npmrc,
+            signal,
+            integrity: node.integrity,
+            onRetry: ({ attempt, error, delayMs }) => {
+                log('tarball %s@%s: retry %d after %dms (%s)', node.name, node.version, attempt, delayMs, errMsg(error));
+            },
+        });
+        // Best-effort cache write — failures are swallowed by `putCachedTarball`
+        // so a read-only HOME / out-of-disk cache volume doesn't break the install.
+        putCachedTarball(node.integrity, bytes);
+    }
     fs.rmSync(dest, { recursive: true, force: true });
     fs.mkdirSync(dest, { recursive: true });
     await extractTarball(bytes, dest);

package/lib/utils/install-backend.d.ts

@@ -1,3 +1,6 @@
+import type { ProgressReporter } from './install-progress.js';
+export type { ProgressEvent, ProgressPhase, ProgressReporter } from './install-progress.js';
+export { makeProgressReporter } from './install-progress.js';
 export interface InstallOptions {
     /** Directory to install into (npm `--prefix`). Created by caller. */
     prefix: string;
@@ -40,6 +43,22 @@ export interface InstallOptions {
      * (npm does its own resolution and does not consult this flag).
      */
     skipDeps?: boolean;
+    /**
+     * Native backend only: overall wall-clock budget for the install. When
+     * fired, in-flight packument + tarball fetches are aborted via their
+     * AbortSignals (the resolver/extractor surface the abort as a normal
+     * AbortError), so the user gets a clean failure instead of a silent
+     * hang. Zero or undefined disables the overall budget — per-request
+     * timeouts in @gjsify/npm-registry still apply.
+     */
+    signal?: AbortSignal;
+    /**
+     * Native backend only: progress reporter for resolve / download / extract /
+     * link phases. The CLI auto-creates a TTY-aware reporter by default; pass
+     * a custom reporter (or the `NOOP` from `makeProgressReporter({enabled:false})`)
+     * to override.
+     */
+    progress?: ProgressReporter;
 }
 export interface InstallResult {
     /** Top-level packages that were requested, with the version each

package/lib/utils/install-backend.js

@@ -15,6 +15,7 @@
 import { spawn } from 'node:child_process';
 import { writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+export { makeProgressReporter } from './install-progress.js';
 const DEFAULT_BACKEND = process.env.GJSIFY_INSTALL_BACKEND ?? 'native';
 export async function installPackages(opts) {
     if (DEFAULT_BACKEND === 'npm') {

package/lib/utils/install-progress.d.ts

@@ -0,0 +1,26 @@
+export type ProgressPhase = 'resolve' | 'download' | 'extract' | 'link';
+export interface ProgressEvent {
+    phase: ProgressPhase;
+    current: number;
+    total: number;
+    /** Package name being processed, surfaced in the right-hand side of the bar. */
+    name?: string;
+}
+export interface ProgressReporter {
+    /** Called for each step within a phase. */
+    update(event: ProgressEvent): void;
+    /** Called once when a phase begins; lets the reporter print a header line. */
+    beginPhase(phase: ProgressPhase, total: number): void;
+    /** Called once when a phase completes; clears the inline progress bar. */
+    endPhase(phase: ProgressPhase): void;
+}
+/**
+ * Make a progress reporter that auto-targets `process.stderr`.
+ * - `enabled=false` → silent.
+ * - stderr is not a TTY → fall back to one line per phase (begin + end).
+ * - stderr is a TTY → live single-line progress bar (\r-updated, 30fps).
+ */
+export declare function makeProgressReporter(opts?: {
+    enabled?: boolean;
+    stream?: NodeJS.WriteStream;
+}): ProgressReporter;

package/lib/utils/install-progress.js

@@ -0,0 +1,109 @@
+// Progress reporter for `gjsify install` + `gjsify dlx`.
+//
+// Auto-enables on TTY stderr. Renders a single-line progress bar that gets
+// overwritten via `\r`, mirroring what `yarn install` / `pnpm install` show:
+//
+//     resolving [████████░░░░░░░░] 234/500 typescript@^6.0.3
+//
+// Falls back to a chatty mode (one line per completed step) when stderr is
+// not a TTY, e.g. when piped into a log file or running on CI.
+//
+// Caller plumbing — the install backend calls `report({phase, current, total,
+// name})` after every resolve/download/extract step; the renderer rate-limits
+// to ~30fps so a tight inner loop doesn't drown the terminal.
+const PHASE_LABEL = {
+    resolve: 'resolving',
+    download: 'downloading',
+    extract: 'extracting',
+    link: 'linking bins',
+};
+const NOOP_REPORTER = {
+    update() { },
+    beginPhase() { },
+    endPhase() { },
+};
+/**
+ * Make a progress reporter that auto-targets `process.stderr`.
+ * - `enabled=false` → silent.
+ * - stderr is not a TTY → fall back to one line per phase (begin + end).
+ * - stderr is a TTY → live single-line progress bar (\r-updated, 30fps).
+ */
+export function makeProgressReporter(opts = {}) {
+    if (opts.enabled === false)
+        return NOOP_REPORTER;
+    const stream = opts.stream ?? process.stderr;
+    const isTty = Boolean(stream.isTTY);
+    const enabled = opts.enabled ?? true;
+    if (!enabled)
+        return NOOP_REPORTER;
+    return isTty ? makeTtyReporter(stream) : makePlainReporter(stream);
+}
+// ──── TTY reporter — single-line, \r-updated, 30fps rate-limit ────────────
+function makeTtyReporter(stream) {
+    let lastRender = 0;
+    let lastLine = '';
+    const FRAME_MS = 33; // ~30fps
+    function render(line, force = false) {
+        const now = Date.now();
+        if (!force && now - lastRender < FRAME_MS && line === lastLine)
+            return;
+        lastRender = now;
+        lastLine = line;
+        // Clear current line, write new content. \x1b[2K = erase entire line.
+        stream.write('\r\x1b[2K' + line);
+    }
+    function clearLine() {
+        stream.write('\r\x1b[2K');
+        lastLine = '';
+    }
+    return {
+        beginPhase(phase, total) {
+            // First frame so the user sees immediate feedback.
+            render(formatBar(phase, 0, total, undefined, stream.columns ?? 80), true);
+        },
+        update(ev) {
+            render(formatBar(ev.phase, ev.current, ev.total, ev.name, stream.columns ?? 80));
+        },
+        endPhase(phase) {
+            // Replace the live bar with a completion line so the user sees
+            // a definitive "done" after the spinner stops.
+            const label = PHASE_LABEL[phase];
+            clearLine();
+            stream.write(`gjsify install: ${label} done\n`);
+        },
+    };
+}
+// ──── Plain reporter — one line per phase begin + end (non-TTY) ────────────
+function makePlainReporter(stream) {
+    return {
+        beginPhase(phase, total) {
+            stream.write(`gjsify install: ${PHASE_LABEL[phase]} ${total} package(s)\n`);
+        },
+        update() {
+            // Per-package output would flood logs; skip on non-TTY.
+        },
+        endPhase(phase) {
+            stream.write(`gjsify install: ${PHASE_LABEL[phase]} done\n`);
+        },
+    };
+}
+// ──── Bar formatter ────────────────────────────────────────────────────────
+function formatBar(phase, current, total, name, columns) {
+    const label = PHASE_LABEL[phase];
+    const ratio = total > 0 ? Math.min(1, current / total) : 0;
+    const pct = `${current}/${total}`;
+    // Reserve: "gjsify install: " (16) + label (max ~12) + " [" (2) + "] " (2) + pct (~8) + " " + name
+    const prefix = `gjsify install: ${label} `;
+    const suffix = ` ${pct}` + (name ? ` ${name}` : '');
+    const barWidth = Math.max(8, Math.min(40, columns - prefix.length - suffix.length - 4));
+    const filled = Math.round(ratio * barWidth);
+    const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
+    let line = `${prefix}[${bar}]${suffix}`;
+    if (line.length > columns) {
+        // Truncate name if the terminal is narrow.
+        const overflow = line.length - columns + 1;
+        const truncatedName = name && name.length > overflow ? name.slice(0, name.length - overflow - 1) + '…' : '';
+        line = `${prefix}[${bar}] ${pct}${truncatedName ? ' ' + truncatedName : ''}`;
+    }
+    return line;
+}

package/lib/utils/install-tarball-cache.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Read a cached tarball by SRI integrity. Returns the raw tarball bytes if
+ * the cache has a HIT, `null` otherwise. A read failure (e.g. partial
+ * write from an interrupted previous run) is treated as a MISS — the file
+ * is left untouched so we don't trip a follow-up writer's atomic rename.
+ */
+export declare function getCachedTarball(integrity: string | undefined): Uint8Array | null;
+/**
+ * Persist a tarball to the cache. Writes to a `<path>.tmp.<pid>` sibling
+ * then atomically renames into place so concurrent installs can never
+ * observe a half-written entry. No-op when:
+ *   - `integrity` is missing / malformed (no cache key)
+ *   - the destination already exists (idempotent — content-addressed)
+ *   - the write fails (e.g. cache root is read-only) — silently degrade
+ *     so a cache-volume issue doesn't break the install itself.
+ */
+export declare function putCachedTarball(integrity: string | undefined, bytes: Uint8Array): void;
+/**
+ * Best-effort cache stats for diagnostics. Returns `null` when the cache
+ * root doesn't exist yet (first run).
+ */
+export declare function cacheRootForLogging(): string;
+export declare function isCacheHit(integrity: string | undefined): boolean;

package/lib/utils/install-tarball-cache.js

@@ -0,0 +1,140 @@
+// Content-addressable tarball cache for `gjsify install`.
+//
+// Mirrors pnpm / yarn-berry's store layout: each tarball is stored once on
+// disk keyed by its SRI integrity hash (`sha512-…`). When the resolver hits
+// a node whose integrity is already cached, `fetchTarball` is skipped and
+// we read the bytes off the local filesystem instead.
+//
+// Why this matters: a cold install on this monorepo (200+ workspaces,
+// 600+ transitive deps) spends ~20 minutes at 80% CPU. Most of that time is
+// re-downloading + re-extracting the SAME tarballs that just came down in
+// the previous run because there is no cache between runs. With this cache,
+// the second `gjsify install` on the same repo skips every tarball fetch
+// and just goes straight to extract → drops well below 1 minute in practice.
+//
+// Layout (matches the pnpm pattern so we stay forward-compatible with
+// `~/.cache/gjsify/store` if we eventually share a store across projects):
+//
+//   $XDG_CACHE_HOME/gjsify/tarballs/v1/<hex-prefix-2>/<full-hex>.tgz
+//
+// The 2-byte prefix is a directory-sharding step so the leaf directory
+// never gets pathologically large — same pattern git's loose objects use.
+// `v1` is a layout version so we can change the file shape (e.g. add a
+// manifest sidecar) without invalidating the world.
+//
+// SRI integrity input → cache key:
+//
+//   "sha512-AbCd…=="   →  ("sha512", "ab/cdefg….tgz")
+//
+// We hex-encode the base64 SRI digest. Two integrities that produce the
+// same hex bytes share the same cache entry; that is the invariant pnpm
+// relies on too. Tarballs without an integrity hash (older registries)
+// fall through to a no-op cache and download every time.
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const CACHE_LAYOUT_VERSION = 'v1';
+/**
+ * Resolve the root of the tarball cache. Mirrors the dlx cache's
+ * XDG-honouring lookup so users with a custom `XDG_CACHE_HOME` get a
+ * single coherent cache root.
+ */
+function cacheRoot() {
+    const xdg = process.env.XDG_CACHE_HOME;
+    const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.cache');
+    return join(base, 'gjsify', 'tarballs', CACHE_LAYOUT_VERSION);
+}
+/**
+ * Convert an SRI integrity string (`sha512-AbCd…=`) into a cache file path.
+ * Returns `null` for unsupported / malformed integrity values so the caller
+ * can fall back to a fresh download.
+ */
+function pathFor(integrity) {
+    if (!integrity)
+        return null;
+    const dashIdx = integrity.indexOf('-');
+    if (dashIdx <= 0 || dashIdx === integrity.length - 1)
+        return null;
+    const algo = integrity.slice(0, dashIdx);
+    const b64 = integrity.slice(dashIdx + 1).replace(/=+$/, '');
+    // Decode base64 → hex; throws on malformed input which we swallow.
+    let hex;
+    try {
+        hex = Buffer.from(b64, 'base64').toString('hex');
+    }
+    catch {
+        return null;
+    }
+    if (hex.length < 4)
+        return null;
+    const shard = hex.slice(0, 2);
+    return join(cacheRoot(), algo, shard, `${hex}.tgz`);
+}
+/**
+ * Read a cached tarball by SRI integrity. Returns the raw tarball bytes if
+ * the cache has a HIT, `null` otherwise. A read failure (e.g. partial
+ * write from an interrupted previous run) is treated as a MISS — the file
+ * is left untouched so we don't trip a follow-up writer's atomic rename.
+ */
+export function getCachedTarball(integrity) {
+    const path = pathFor(integrity);
+    if (!path)
+        return null;
+    if (!existsSync(path))
+        return null;
+    try {
+        const buf = readFileSync(path);
+        // Sanity: a zero-byte file is a previous-write failure; treat as MISS.
+        if (buf.length === 0)
+            return null;
+        return buf;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist a tarball to the cache. Writes to a `<path>.tmp.<pid>` sibling
+ * then atomically renames into place so concurrent installs can never
+ * observe a half-written entry. No-op when:
+ *   - `integrity` is missing / malformed (no cache key)
+ *   - the destination already exists (idempotent — content-addressed)
+ *   - the write fails (e.g. cache root is read-only) — silently degrade
+ *     so a cache-volume issue doesn't break the install itself.
+ */
+export function putCachedTarball(integrity, bytes) {
+    const path = pathFor(integrity);
+    if (!path)
+        return;
+    if (existsSync(path))
+        return;
+    try {
+        mkdirSync(join(path, '..'), { recursive: true });
+        const tmp = `${path}.tmp.${process.pid}`;
+        writeFileSync(tmp, bytes);
+        renameSync(tmp, path);
+    }
+    catch {
+        // Cache write failure is non-fatal — the install proceeds with the
+        // in-memory bytes; we just won't get a hit on the next run.
+    }
+}
+/**
+ * Best-effort cache stats for diagnostics. Returns `null` when the cache
+ * root doesn't exist yet (first run).
+ */
+export function cacheRootForLogging() {
+    return cacheRoot();
+}
+export function isCacheHit(integrity) {
+    const path = pathFor(integrity);
+    if (!path)
+        return false;
+    try {
+        const s = statSync(path);
+        return s.isFile() && s.size > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/lib/utils/load-npmrc.d.ts

@@ -0,0 +1,14 @@
+import { type NpmrcConfig } from '@gjsify/npm-registry';
+export declare function loadNpmrc(cwd: string): Promise<NpmrcConfig>;
+/**
+ * True iff the parsed npmrc contains *any* `_authToken` entry. Cheap helper
+ * for commands that want a clear "no token configured" error message
+ * instead of a generic 401/empty response.
+ */
+export declare function hasAnyAuthToken(npmrc: NpmrcConfig): boolean;
+/**
+ * True iff the parsed npmrc has *any* credential (bearer token or basic
+ * auth). Used by `gjsify whoami` to differentiate "no token configured"
+ * from "token configured but rejected by the registry".
+ */
+export declare function hasAnyCredential(npmrc: NpmrcConfig): boolean;

package/lib/utils/load-npmrc.js

@@ -0,0 +1,61 @@
+// Shared npmrc loader for `gjsify publish` / `gjsify whoami` / future
+// auth-aware commands. Mirrors npm CLI's resolution order so a maintainer's
+// `~/.npmrc` token AND a CI-injected `NPM_CONFIG_USERCONFIG` token both
+// reach the registry call.
+//
+// Resolution order (lowest → highest precedence — last write wins on key
+// collisions because the sources are concatenated and re-parsed):
+//   1. globalconfig:  /etc/npmrc  (system; intentionally NOT read here —
+//                     gjsify's user-facing commands operate on per-user
+//                     credentials, matching `npm whoami`'s behavior)
+//   2. userconfig:    $NPM_CONFIG_USERCONFIG  (overrides ~/.npmrc)
+//                     or ~/.npmrc  (default)
+//   3. projectconfig: ./.npmrc  (closest workspace)
+//
+// `actions/setup-node` writes the auth-token npmrc to $RUNNER_TEMP/.npmrc
+// and exports NPM_CONFIG_USERCONFIG pointing at it — it does NOT touch
+// ~/.npmrc. Honor the env var so CI authentication works end-to-end.
+//
+// `${VAR}` placeholders are expanded inline (npm CLI's expand-on-read
+// behavior). The auth-token npmrc from actions/setup-node ships
+// `_authToken=${NODE_AUTH_TOKEN}` as a literal placeholder; the env var is
+// set on the publish step.
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parseNpmrc } from '@gjsify/npm-registry';
+export async function loadNpmrc(cwd) {
+    const sources = [];
+    const projectNpmrc = join(cwd, '.npmrc');
+    if (existsSync(projectNpmrc))
+        sources.push(readFileSync(projectNpmrc, 'utf-8'));
+    const userConfig = process.env.NPM_CONFIG_USERCONFIG;
+    if (userConfig && existsSync(userConfig)) {
+        sources.push(readFileSync(userConfig, 'utf-8'));
+    }
+    else {
+        const homeNpmrc = join(homedir(), '.npmrc');
+        if (existsSync(homeNpmrc))
+            sources.push(readFileSync(homeNpmrc, 'utf-8'));
+    }
+    const merged = sources
+        .join('\n')
+        .replace(/\$\{([A-Z_][A-Z0-9_]*)\}/gi, (_, name) => process.env[name] ?? '');
+    return parseNpmrc(merged);
+}
+/**
+ * True iff the parsed npmrc contains *any* `_authToken` entry. Cheap helper
+ * for commands that want a clear "no token configured" error message
+ * instead of a generic 401/empty response.
+ */
+export function hasAnyAuthToken(npmrc) {
+    return Object.keys(npmrc.authTokens).length > 0;
+}
+/**
+ * True iff the parsed npmrc has *any* credential (bearer token or basic
+ * auth). Used by `gjsify whoami` to differentiate "no token configured"
+ * from "token configured but rejected by the registry".
+ */
+export function hasAnyCredential(npmrc) {
+    return hasAnyAuthToken(npmrc) || Object.keys(npmrc.basicAuth).length > 0;
+}

package/lib/utils/publish-diagnose.d.ts

@@ -0,0 +1,38 @@
+import { type NpmrcConfig } from '@gjsify/npm-registry';
+export type Diagnose404Reason = 'dead-token' | 'live-token-404' | 'unknown';
+export interface Diagnose404Result {
+    /** Discriminant — drives the JSON shape + exit-code path in the caller. */
+    reason: Diagnose404Reason;
+    /** Username from `/-/whoami` when reason === 'live-token-404'. */
+    username?: string;
+    /** Multi-line, human-friendly hint ready for stderr emission. */
+    message: string;
+}
+interface Diagnose404Input {
+    /** Full package name including scope, e.g. `@gjsify/abort-controller`. */
+    packageName: string;
+    /** Pinned version we tried to publish. */
+    version: string;
+    /** Registry URL (with or without trailing slash). */
+    registry: string;
+    /** Parsed .npmrc — used to derive Authorization on the whoami probe. */
+    npmrc: NpmrcConfig | undefined;
+}
+/**
+ * Probe `/-/whoami` to disambiguate the 404 cause. Best-effort: any thrown
+ * error / non-2xx falls through to `reason: 'unknown'` so the caller's
+ * generic error path runs untouched.
+ *
+ * Pure async I/O — no side effects, no process.exit, no console writes.
+ * The caller owns presentation (stderr vs stdout, plain vs JSON).
+ */
+export declare function diagnose404(input: Diagnose404Input): Promise<Diagnose404Result>;
+/**
+ * Heuristic: is the 404 body the "dead-token-or-missing-package" shape?
+ * npm's PUT returns plain text `Not Found` (sometimes empty body). We trigger
+ * the diagnostic for both, plus for the JSON `{"error":"Not Found"}` shape
+ * just in case. Other 404 bodies (e.g. with a structured npm error code)
+ * keep the generic error path.
+ */
+export declare function is404DiagnosticCandidate(body: string): boolean;
+export {};