@gjsify/cli 0.4.35 → 0.4.37

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

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: MIT
+// Shared filesystem primitives for `gjsify install`'s on-disk caches.
+//
+// Both the content-addressable tarball cache (install-tarball-cache.ts) and the
+// packument metadata cache (install-packument-cache.ts) need the same three
+// things: an `XDG_CACHE_HOME`-honouring cache root, an atomic write (so a
+// concurrent install never observes a half-written entry), and a read that
+// treats a missing / zero-byte / unreadable file as a MISS. Centralising them
+// here keeps the two caches byte-for-byte consistent.
+//
+// Out of scope: the dlx cache (`dlx-cache.ts`) has a different layout
+// (`gjsify/dlx`, sha256 + symlink-swap) and its own TTL/prepare-dir concerns —
+// it is a precedent for the XDG helper, not a reuse target.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Resolve `$XDG_CACHE_HOME/gjsify/<kind>/<layoutVersion>` (falling back to
+ * `~/.cache` when `XDG_CACHE_HOME` is unset/empty). `kind` is the cache area
+ * (`tarballs`, `metadata`); `layoutVersion` lets one cache evolve its on-disk
+ * shape without invalidating its siblings.
+ */
+export function gjsifyCacheRoot(kind, layoutVersion) {
+    const xdg = process.env.XDG_CACHE_HOME;
+    const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.cache');
+    return join(base, 'gjsify', kind, layoutVersion);
+}
+/**
+ * Write `bytes` to `path` atomically: write a `<path>.tmp.<pid>` sibling, then
+ * `rename` it into place, so a concurrent reader never observes a half-written
+ * file. Creates the parent directory. Best-effort — any failure (read-only /
+ * out-of-disk cache volume) is swallowed so a cache hiccup never breaks the
+ * install; the caller proceeds with its in-memory copy.
+ */
+export function atomicWrite(path, bytes) {
+    try {
+        mkdirSync(join(path, '..'), { recursive: true });
+        const tmp = `${path}.tmp.${process.pid}`;
+        writeFileSync(tmp, bytes);
+        renameSync(tmp, path);
+    }
+    catch {
+        /* best-effort — a cache-write failure must not break the install */
+    }
+}
+/**
+ * Read a cache file, returning its bytes on a HIT or `null` on a MISS. A
+ * missing file, a zero-byte file (an interrupted previous write), or any read
+ * error are all treated as a MISS — the file is left untouched so a follow-up
+ * writer's atomic rename isn't disturbed.
+ */
+export function readCacheFile(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const buf = readFileSync(path);
+        if (buf.length === 0)
+            return null;
+        return buf;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { Packument } from '@gjsify/npm-registry';
+export interface CachedPackument {
+    etag: string;
+    packument: Packument;
+}
+/**
+ * Read a cached packument + its ETag for `(registry, name)`. Returns `null` on
+ * a miss, when the cache is disabled, or when the entry is unreadable/corrupt
+ * (treated as a miss — the caller just re-fetches).
+ */
+export declare function getCachedPackument(registry: string, name: string): CachedPackument | null;
+/**
+ * Persist a packument + ETag for `(registry, name)`. Writes to a `<path>.tmp.<pid>`
+ * sibling then atomically renames so a concurrent reader never sees a partial
+ * write. No-op when the cache is disabled, the ETag is empty, or the write
+ * fails (read-only / out-of-disk cache volume must not break the install).
+ */
+export declare function putCachedPackument(registry: string, name: string, etag: string, packument: Packument): void;

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

@@ -0,0 +1,98 @@
+// On-disk packument metadata cache for `gjsify install`.
+//
+// Sibling to the content-addressable tarball cache (install-tarball-cache.ts).
+// Stores each package's abbreviated packument plus the registry `ETag` it came
+// with, so a re-resolve (lockfile miss — e.g. a dependency range changed) can
+// send a conditional `If-None-Match` and turn the unchanged majority into empty
+// `304 Not Modified` responses — a real bandwidth + parse saving on repeated /
+// dep-churn installs, on top of the ~4× gzip transfer for the changed minority
+// (packuments are fetched gzip-compressed and decoded by the fetch layer; see
+// `@gjsify/npm-registry` `fetchPackumentConditional`).
+//
+// Mirrors pnpm's metadata cache + npm's make-fetch-happen HTTP-cache layer.
+//
+// Layout:
+//
+//   $XDG_CACHE_HOME/gjsify/metadata/v1/<shard>/<encoded-registry>|<encoded-name>.json
+//
+// The cache is keyed by (registry, name) — NOT name alone — so switching the
+// registry for a scope can never serve a packument from the wrong source on a
+// coincidental ETag match. `<shard>` is a 2-hex FNV-1a digest of the key, a
+// directory-fan-out step so the leaf dir never grows unbounded (same rationale
+// as the tarball cache's hex sharding). `v1` is a layout version.
+//
+// Disabled with `GJSIFY_PACKUMENT_CACHE=0` (or `false`). Honours
+// `XDG_CACHE_HOME` like the tarball + dlx caches.
+import { join } from 'node:path';
+import { atomicWrite, gjsifyCacheRoot, readCacheFile } from './install-cache-fs.js';
+const CACHE_LAYOUT_VERSION = 'v1';
+/** `true` unless `GJSIFY_PACKUMENT_CACHE` is `0` / `false` / empty. */
+function isEnabled() {
+    const flag = process.env.GJSIFY_PACKUMENT_CACHE;
+    if (flag === undefined)
+        return true;
+    const trimmed = flag.trim();
+    return !(trimmed === '0' || trimmed === 'false' || trimmed === '');
+}
+/** Root of the packument cache: `$XDG_CACHE_HOME/gjsify/metadata/v1`. */
+function cacheRoot() {
+    return gjsifyCacheRoot('metadata', CACHE_LAYOUT_VERSION);
+}
+/** FNV-1a 32-bit → 2 hex chars. Directory-fan-out only; not security-sensitive. */
+function shardFor(key) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < key.length; i++) {
+        h ^= key.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return ((h >>> 0) & 0xff).toString(16).padStart(2, '0');
+}
+/** Filesystem path for a (registry, name) pair, or `null` when disabled. */
+function pathFor(registry, name) {
+    if (!isEnabled())
+        return null;
+    const key = `${registry}|${name}`;
+    // encodeURIComponent makes both halves filesystem-safe (`/` → `%2F`, etc.)
+    // while staying a stable, reversible, single path segment.
+    const file = `${encodeURIComponent(registry)}|${encodeURIComponent(name)}.json`;
+    return join(cacheRoot(), shardFor(key), file);
+}
+/**
+ * Read a cached packument + its ETag for `(registry, name)`. Returns `null` on
+ * a miss, when the cache is disabled, or when the entry is unreadable/corrupt
+ * (treated as a miss — the caller just re-fetches).
+ */
+export function getCachedPackument(registry, name) {
+    const path = pathFor(registry, name);
+    if (!path)
+        return null;
+    const buf = readCacheFile(path);
+    if (!buf)
+        return null;
+    try {
+        const parsed = JSON.parse(buf.toString('utf-8'));
+        if (typeof parsed.etag !== 'string' || !parsed.etag)
+            return null;
+        if (!parsed.packument || typeof parsed.packument !== 'object')
+            return null;
+        return { etag: parsed.etag, packument: parsed.packument };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist a packument + ETag for `(registry, name)`. Writes to a `<path>.tmp.<pid>`
+ * sibling then atomically renames so a concurrent reader never sees a partial
+ * write. No-op when the cache is disabled, the ETag is empty, or the write
+ * fails (read-only / out-of-disk cache volume must not break the install).
+ */
+export function putCachedPackument(registry, name, etag, packument) {
+    if (!etag)
+        return;
+    const path = pathFor(registry, name);
+    if (!path)
+        return;
+    const entry = { etag, packument };
+    atomicWrite(path, JSON.stringify(entry));
+}

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,31 @@
+/**
+ * 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;
+/**
+ * Read a tarball from npm's cacache content store by SRI integrity. Returns
+ * the raw `.tgz` bytes on a HIT, `null` on a MISS / disabled interop / read
+ * failure. Like {@link getCachedTarball}, this trusts the content-addressed
+ * path rather than re-hashing — the extractor surfaces any genuinely corrupt
+ * tarball loudly, and cacache verified the bytes on write.
+ */
+export declare function getForeignCachedTarball(integrity: string | undefined): Uint8Array | null;

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

@@ -0,0 +1,192 @@
+// 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, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { atomicWrite, gjsifyCacheRoot, readCacheFile } from './install-cache-fs.js';
+const CACHE_LAYOUT_VERSION = 'v1';
+/** Root of the tarball cache: `$XDG_CACHE_HOME/gjsify/tarballs/v1`. */
+function cacheRoot() {
+    return gjsifyCacheRoot('tarballs', CACHE_LAYOUT_VERSION);
+}
+/**
+ * Parse an SRI integrity string (`sha512-AbCd…=`) into its algorithm + hex
+ * digest, or `null` for a missing / malformed value (caller falls back to a
+ * fresh download). Shared by both the gjsify-store and npm-cacache path
+ * derivations below — the base64→hex decode used to be inlined in each.
+ */
+function parseSri(integrity) {
+    if (!integrity)
+        return null;
+    const dashIdx = integrity.indexOf('-');
+    if (dashIdx <= 0 || dashIdx === integrity.length - 1)
+        return null;
+    const algorithm = 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;
+    return { algorithm, hex };
+}
+/**
+ * Convert an SRI integrity string 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) {
+    const sri = parseSri(integrity);
+    if (!sri)
+        return null;
+    const shard = sri.hex.slice(0, 2);
+    return join(cacheRoot(), sri.algorithm, shard, `${sri.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;
+    return readCacheFile(path);
+}
+/**
+ * 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;
+    // Idempotent: content-addressed entries are immutable, never rewritten.
+    if (existsSync(path))
+        return;
+    atomicWrite(path, bytes);
+}
+/**
+ * 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;
+    }
+}
+// ---------------------------------------------------------------------------
+// Foreign cache interop — read npm's cacache content store.
+//
+// npm stores downloaded tarballs in a content-addressable store
+// (`cacache`) keyed by the SAME SRI integrity we key our own store on, and
+// holds the raw `.tgz` bytes verbatim. Layout (cacache `content-v2`):
+//
+//   <npm-cache>/_cacache/content-v2/<algo>/<hex[0:2]>/<hex[2:4]>/<hex[4:]>
+//
+// `<algo>` is the SRI algorithm (`sha512`), `<hex>` the hex-encoded digest —
+// identical derivation to our own `pathFor`, just a different root and no
+// `.tgz` extension. So anyone who has run `npm install` before already has
+// these tarballs on disk; reading them turns a cold `gjsify install` into a
+// near-warm one without a single network round-trip.
+//
+// pnpm/yarn/bun stores are deliberately NOT read here: pnpm/bun store
+// *unpacked* per-file content (no tarball to hand to the extractor) and yarn
+// berry stores zip archives under its own (non-SRI) cache key — none map to a
+// tarball-by-integrity lookup the way npm's cacache does.
+// ---------------------------------------------------------------------------
+/**
+ * Resolve npm's `content-v2` directory, honouring `GJSIFY_NPM_CACHE`
+ * (full path to a `_cacache` dir; `0`/`false`/empty disables the interop),
+ * then `npm_config_cache`, then the platform default `~/.npm`. Returns `null`
+ * when the interop is disabled or no plausible cache root exists.
+ */
+function npmCacacheContentDir() {
+    const override = process.env.GJSIFY_NPM_CACHE;
+    if (override !== undefined) {
+        const trimmed = override.trim();
+        if (trimmed === '' || trimmed === '0' || trimmed === 'false')
+            return null;
+        // Accept either the `_cacache` dir itself or its parent npm cache dir.
+        const base = trimmed.endsWith('_cacache') ? trimmed : join(trimmed, '_cacache');
+        return join(base, 'content-v2');
+    }
+    const npmConfigCache = process.env.npm_config_cache;
+    const cacheBase = npmConfigCache && npmConfigCache.length > 0 ? npmConfigCache : join(homedir(), '.npm');
+    return join(cacheBase, '_cacache', 'content-v2');
+}
+/** Map an SRI integrity to its npm cacache content-store path, or `null`. */
+function npmCachePathFor(integrity) {
+    const contentDir = npmCacacheContentDir();
+    if (!contentDir)
+        return null;
+    const sri = parseSri(integrity);
+    if (!sri)
+        return null;
+    // cacache shards the hex digest into [0:2]/[2:4]/[4:] with NO extension.
+    return join(contentDir, sri.algorithm, sri.hex.slice(0, 2), sri.hex.slice(2, 4), sri.hex.slice(4));
+}
+/**
+ * Read a tarball from npm's cacache content store by SRI integrity. Returns
+ * the raw `.tgz` bytes on a HIT, `null` on a MISS / disabled interop / read
+ * failure. Like {@link getCachedTarball}, this trusts the content-addressed
+ * path rather than re-hashing — the extractor surfaces any genuinely corrupt
+ * tarball loudly, and cacache verified the bytes on write.
+ */
+export function getForeignCachedTarball(integrity) {
+    const path = npmCachePathFor(integrity);
+    if (!path)
+        return null;
+    return readCacheFile(path);
+}

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/prompt.d.ts

@@ -0,0 +1,8 @@
+/** Print a question and read one line from stdin (visible). */
+export declare function promptLine(question: string): Promise<string>;
+/**
+ * Print a question and read one line WITHOUT echoing it (passwords). Uses raw
+ * mode + manual key handling on a TTY; falls back to a plain line read when
+ * stdin is not a TTY (piped). Ctrl-C aborts the process.
+ */
+export declare function promptHidden(question: string): Promise<string>;