@gjsify/cli 0.4.35 → 0.4.37

package/lib/index.js

@@ -4,7 +4,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
-import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, } from './commands/index.js';
+import { buildCommand as build, testCommand as test, runCommand as run, infoCommand as info, systemCheckCommand as systemCheck, checkCommand as check, showcaseCommand as showcase, createCommand as create, gresourceCommand as gresource, gettextCommand as gettext, gsettingsCommand as gsettings, flatpakCommand as flatpak, dlxCommand as dlx, installCommand as install, foreachCommand as foreach, workspaceCommand as workspace, packCommand as pack, publishCommand as publish, whoamiCommand as whoami, loginCommand as login, logoutCommand as logout, selfUpdateCommand as selfUpdate, generateInstallerCommand as generateInstaller, uninstallCommand as uninstall, formatCommand as format, lintCommand as lint, fixCommand as fix, upgradeCommand as upgrade, barrelsCommand as barrels, tscCommand as tsc, affectedCommand as affected, } from './commands/index.js';
 import { APP_NAME } from './constants.js';
 // Detect which runtime is executing the CLI (GJS or Node.js).
 // GJS MUST be checked first because @gjsify/process sets
@@ -79,6 +79,9 @@ await cli
     .command(workspace.command, workspace.description, workspace.builder, workspace.handler)
     .command(pack.command, pack.description, pack.builder, pack.handler)
     .command(publish.command, publish.description, publish.builder, publish.handler)
+    .command(whoami.command, whoami.description, whoami.builder, whoami.handler)
+    .command(login.command, login.description, login.builder, login.handler)
+    .command(logout.command, logout.description, logout.builder, logout.handler)
     .command(selfUpdate.command, selfUpdate.description, selfUpdate.builder, selfUpdate.handler)
     .command(generateInstaller.command, generateInstaller.description, generateInstaller.builder, generateInstaller.handler)
     .command(uninstall.command, uninstall.description, uninstall.builder, uninstall.handler)
@@ -87,6 +90,8 @@ await cli
     .command(lint.command, lint.description, lint.builder, lint.handler)
     .command(fix.command, fix.description, fix.builder, fix.handler)
     .command(barrels.command, barrels.description, barrels.builder, barrels.handler)
+    .command(tsc.command, tsc.description, tsc.builder, tsc.handler)
+    .command(affected.command, affected.description, affected.builder, affected.handler)
     .demandCommand(1)
     .epilogue(`Running on ${runtimeLabel()}`)
     .help()

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

@@ -0,0 +1,22 @@
+/** The `.npmrc` file `gjsify login` writes to (matches `load-npmrc.ts`'s userconfig source). */
+export declare function userconfigNpmrcPath(): string;
+/**
+ * The npm "nerf-dart" key for a registry: the URL with the protocol removed,
+ * keeping the host + path with a trailing slash — `//registry.npmjs.org/`.
+ */
+export declare function nerfDart(registry: string): string;
+/** The full `_authToken` config key for a registry. */
+export declare function authTokenKey(registry: string): string;
+/**
+ * Upsert `<nerf-dart>:_authToken=<token>` in the userconfig `.npmrc`, preserving
+ * all other lines. Returns the file path written.
+ */
+export declare function writeAuthToken(registry: string, token: string): string;
+/**
+ * Remove the `<nerf-dart>:_authToken=` line for a registry from the userconfig
+ * `.npmrc`. Returns `{ path, removed }` — `removed` is false if no line matched.
+ */
+export declare function removeAuthToken(registry: string): {
+    path: string;
+    removed: boolean;
+};

package/lib/utils/auth-npmrc.js

@@ -0,0 +1,89 @@
+// Write/remove npm auth tokens in the user's `.npmrc` — the write side of
+// `load-npmrc.ts` (which only reads). Used by `gjsify login` / `gjsify logout`.
+//
+// npm stores the token under a "nerf-dart" key: the registry URL with the
+// protocol stripped, e.g. `//registry.npmjs.org/:_authToken=<token>`. We upsert
+// exactly that line in the userconfig file (`$NPM_CONFIG_USERCONFIG` or
+// `~/.npmrc`), preserving every other line, and chmod it to 0600 (it holds a
+// credential).
+import { existsSync, readFileSync, writeFileSync, chmodSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+/** The `.npmrc` file `gjsify login` writes to (matches `load-npmrc.ts`'s userconfig source). */
+export function userconfigNpmrcPath() {
+    return process.env.NPM_CONFIG_USERCONFIG || join(homedir(), '.npmrc');
+}
+/**
+ * The npm "nerf-dart" key for a registry: the URL with the protocol removed,
+ * keeping the host + path with a trailing slash — `//registry.npmjs.org/`.
+ */
+export function nerfDart(registry) {
+    const u = new URL(registry);
+    const path = u.pathname.endsWith('/') ? u.pathname : `${u.pathname}/`;
+    return `//${u.host}${path}`;
+}
+/** The full `_authToken` config key for a registry. */
+export function authTokenKey(registry) {
+    return `${nerfDart(registry)}:_authToken`;
+}
+function readUserconfig(path) {
+    return existsSync(path) ? readFileSync(path, 'utf-8') : '';
+}
+function writeUserconfig(path, content) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(path, content, 'utf-8');
+    // Credential file — restrict to the owner (best-effort; ignored on Windows).
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        /* non-POSIX filesystem */
+    }
+}
+/**
+ * Upsert `<nerf-dart>:_authToken=<token>` in the userconfig `.npmrc`, preserving
+ * all other lines. Returns the file path written.
+ */
+export function writeAuthToken(registry, token) {
+    const path = userconfigNpmrcPath();
+    const key = authTokenKey(registry);
+    const line = `${key}=${token}`;
+    const existing = readUserconfig(path);
+    const lines = existing.length ? existing.split('\n') : [];
+    let replaced = false;
+    const next = lines.map((l) => {
+        // Match the key at the start of the line (ignore `${...}` placeholder
+        // values too — we always overwrite with the concrete token).
+        if (l.replace(/\s+/g, '').startsWith(`${key}=`)) {
+            replaced = true;
+            return line;
+        }
+        return l;
+    });
+    // Strip trailing blank lines so we don't accumulate them across rewrites.
+    while (next.length && next[next.length - 1].trim() === '')
+        next.pop();
+    if (!replaced)
+        next.push(line);
+    writeUserconfig(path, next.join('\n') + '\n');
+    return path;
+}
+/**
+ * Remove the `<nerf-dart>:_authToken=` line for a registry from the userconfig
+ * `.npmrc`. Returns `{ path, removed }` — `removed` is false if no line matched.
+ */
+export function removeAuthToken(registry) {
+    const path = userconfigNpmrcPath();
+    const key = authTokenKey(registry);
+    const existing = readUserconfig(path);
+    if (!existing)
+        return { path, removed: false };
+    const lines = existing.split('\n');
+    const next = lines.filter((l) => !l.replace(/\s+/g, '').startsWith(`${key}=`));
+    const removed = next.length !== lines.length;
+    if (removed)
+        writeUserconfig(path, next.join('\n'));
+    return { path, removed };
+}

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

@@ -17,9 +17,16 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 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 { DEFAULT_REGISTRY, fetchPackument, fetchPackumentConditional, fetchTarball, parseNpmrc, registryFor, } from '@gjsify/npm-registry';
 import { extractTarball } from '@gjsify/tar';
-const DEFAULT_CONCURRENCY = Number(process.env.GJSIFY_INSTALL_CONCURRENCY ?? '8') || 8;
+import { getCachedTarball, getForeignCachedTarball, putCachedTarball, } from './install-tarball-cache.js';
+import { getCachedPackument, putCachedPackument } from './install-packument-cache.js';
+// 16-wide download pool. Matched to the shared Soup.Session's lifted
+// `max-conns-per-host` (see @gjsify/fetch `getSharedSession`) — a higher pool
+// here only translates into real concurrency because that cap was raised from
+// libsoup's default of 2. npm (`maxsockets` 15) and pnpm (`network-concurrency`
+// 16) use the same order of magnitude. Override with GJSIFY_INSTALL_CONCURRENCY.
+const DEFAULT_CONCURRENCY = Number(process.env.GJSIFY_INSTALL_CONCURRENCY ?? '16') || 16;
 const LOCKFILE_NAME = 'gjsify-lock.json';
 const LOCKFILE_VERSION = 2;
 export async function installPackagesNative(opts) {
@@ -29,6 +36,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 +64,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 +127,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;
@@ -136,12 +145,7 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps) {
         const cached = packumentCache.get(name);
         if (cached)
             return cached;
-        const fresh = fetchPackument(name, {
-            npmrc,
-            onRetry: ({ attempt, error, delayMs }) => {
-                log('packument %s: retry %d after %dms (%s)', name, attempt, delayMs, errMsg(error));
-            },
-        });
+        const fresh = fetchPackumentWithDiskCache(name, npmrc, log, signal);
         packumentCache.set(name, fresh);
         return fresh;
     };
@@ -155,83 +159,189 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps) {
         range: applyOverride(s.name, s.range),
         required: true,
     }));
+    // Wave-based BFS. Each iteration drains the current queue level, prefetches
+    // every not-yet-cached packument in that level IN PARALLEL (bounded), then
+    // applies placement SERIALLY in the same FIFO order the single-edge loop
+    // used. Because newly-discovered children always append to the end of the
+    // queue, "the current queue contents" is exactly one BFS level — so the
+    // serial pass visits edges in the identical order, and `decidePlacement`'s
+    // order-dependent hoist/nest decisions (hence the lockfile) are byte-for-
+    // byte unchanged. Only the network moved: N sequential ~RTT packument
+    // fetches per level collapse into one bounded-parallel batch. This is the
+    // dominant cold-install cost — at libsoup's old `max-conns-per-host=2` it
+    // would have throttled anyway, so it lands alongside the connection-cap
+    // lift in `@gjsify/fetch`. `packumentCache` still guarantees ≤1 fetch per
+    // unique name across the whole resolve, so prefetching every wave name
+    // fetches exactly the same SET as before, just batched.
     while (queue.length > 0) {
-        const edge = queue.shift();
-        // Walk the ancestor chain to see whether a satisfying placement is
-        // already visible from the requester's `node_modules` lookup. npm's
-        // resolver does this — each level of nesting acts as a fallback.
-        const visible = findVisible(edge.from, edge.name, byPath);
-        if (visible && satisfiesRange(visible.version, edge.range)) {
-            // Compatible placement reachable; reuse, no new install.
-            continue;
+        const wave = queue.splice(0, queue.length);
+        // Prefetch every not-yet-cached packument referenced in this level.
+        // Names already in `packumentCache` (resolved in an earlier wave, or a
+        // duplicate within this one) are skipped — the de-dup keeps the batch
+        // to genuinely-new names.
+        const toPrefetch = [];
+        const queuedForFetch = new Set();
+        for (const edge of wave) {
+            if (packumentCache.has(edge.name) || queuedForFetch.has(edge.name))
+                continue;
+            queuedForFetch.add(edge.name);
+            toPrefetch.push(edge.name);
         }
-        // No compatible existing placement. Resolve a fresh version.
-        let version = null;
-        try {
-            const packument = await fetchPkg(edge.name);
-            version = pickVersion(packument, edge.range);
-            if (!version) {
-                if (!edge.required)
-                    continue;
-                throw new Error(`No version of ${edge.name} satisfies ${edge.range}`);
-            }
-            const v = packument.versions[version];
-            if (!v) {
-                throw new Error(`Packument for ${edge.name} promised ${version} but no entry exists`);
-            }
-            // Decision: hoist to root, or nest under the requester?
-            //   - Hoist iff the root has no conflicting placement (i.e. the
-            //     root slot for `name` is empty OR holds the same version).
-            //   - Otherwise nest. Top-level specs (from === null) always
-            //     hoist; the resolver guarantees they never conflict with
-            //     each other because the input set is checked once.
-            const installPath = decidePlacement(edge.from, edge.name, version, root);
-            const node = {
-                name: edge.name,
-                version,
-                tarballUrl: v.dist.tarball,
-                integrity: v.dist.integrity,
-                installPath,
-                dependencies: v.dependencies ?? {},
-                optionalDependencies: v.optionalDependencies ?? {},
-                bin: v.bin,
-            };
-            byPath.set(installPath, node);
-            if (installPath === `node_modules/${edge.name}`) {
-                root.set(edge.name, node);
+        await prefetchPackuments(toPrefetch, fetchPkg, signal);
+        // Serial placement pass — identical decisions and order to the original
+        // single-edge loop, but every `fetchPkg` now resolves from the warmed
+        // cache instead of blocking on a fresh round-trip.
+        for (let wi = 0; wi < wave.length; wi++) {
+            const edge = wave[wi];
+            // Walk the ancestor chain to see whether a satisfying placement is
+            // already visible from the requester's `node_modules` lookup. npm's
+            // resolver does this — each level of nesting acts as a fallback.
+            const visible = findVisible(edge.from, edge.name, byPath);
+            if (visible && satisfiesRange(visible.version, edge.range)) {
+                // Compatible placement reachable; reuse, no new install.
+                continue;
             }
-            log('resolve: %s@%s ← %s (at %s)', edge.name, version, edge.range, installPath);
-            if (!skipDeps) {
-                for (const [depName, depRange] of Object.entries(node.dependencies)) {
-                    queue.push({
-                        from: installPath,
-                        name: depName,
-                        range: applyOverride(depName, depRange),
-                        required: true,
-                    });
+            // No compatible existing placement. Resolve a fresh version.
+            let version = null;
+            try {
+                const packument = await fetchPkg(edge.name);
+                version = pickVersion(packument, edge.range);
+                if (!version) {
+                    if (!edge.required)
+                        continue;
+                    throw new Error(`No version of ${edge.name} satisfies ${edge.range}`);
+                }
+                const v = packument.versions[version];
+                if (!v) {
+                    throw new Error(`Packument for ${edge.name} promised ${version} but no entry exists`);
                 }
-                for (const [depName, depRange] of Object.entries(node.optionalDependencies)) {
-                    queue.push({
-                        from: installPath,
-                        name: depName,
-                        range: applyOverride(depName, depRange),
-                        required: false,
-                    });
+                // Decision: hoist to root, or nest under the requester?
+                //   - Hoist iff the root has no conflicting placement (i.e. the
+                //     root slot for `name` is empty OR holds the same version).
+                //   - Otherwise nest. Top-level specs (from === null) always
+                //     hoist; the resolver guarantees they never conflict with
+                //     each other because the input set is checked once.
+                const installPath = decidePlacement(edge.from, edge.name, version, root);
+                const node = {
+                    name: edge.name,
+                    version,
+                    tarballUrl: v.dist.tarball,
+                    integrity: v.dist.integrity,
+                    installPath,
+                    dependencies: v.dependencies ?? {},
+                    optionalDependencies: v.optionalDependencies ?? {},
+                    bin: v.bin,
+                };
+                byPath.set(installPath, node);
+                if (installPath === `node_modules/${edge.name}`) {
+                    root.set(edge.name, node);
+                }
+                log('resolve: %s@%s ← %s (at %s)', edge.name, version, edge.range, installPath);
+                // Moving soft-total: resolved so far + edges still to visit in
+                // this wave + children already queued for the next wave. Same
+                // converging-estimate pattern yarn/pnpm use.
+                progress?.update({
+                    phase: 'resolve',
+                    current: byPath.size,
+                    total: byPath.size + (wave.length - wi - 1) + queue.length,
+                    name: `${edge.name}@${version}`,
+                });
+                if (!skipDeps) {
+                    for (const [depName, depRange] of Object.entries(node.dependencies)) {
+                        queue.push({
+                            from: installPath,
+                            name: depName,
+                            range: applyOverride(depName, depRange),
+                            required: true,
+                        });
+                    }
+                    for (const [depName, depRange] of Object.entries(node.optionalDependencies)) {
+                        queue.push({
+                            from: installPath,
+                            name: depName,
+                            range: applyOverride(depName, depRange),
+                            required: false,
+                        });
+                    }
                 }
             }
-        }
-        catch (e) {
-            // Optional deps that fail to resolve are skipped — yarn/npm
-            // behavior. Required deps re-throw.
-            if (!edge.required) {
-                log('resolve: optional dep %s@%s skipped (%s)', edge.name, edge.range, e.message);
-                continue;
+            catch (e) {
+                // Optional deps that fail to resolve are skipped — yarn/npm
+                // behavior. Required deps re-throw.
+                if (!edge.required) {
+                    log('resolve: optional dep %s@%s skipped (%s)', edge.name, edge.range, e.message);
+                    continue;
+                }
+                throw e;
             }
-            throw e;
         }
     }
+    progress?.endPhase('resolve');
     return Array.from(byPath.values());
 }
+/**
+ * Warm `packumentCache` for a batch of package names with bounded parallelism
+ * (same `DEFAULT_CONCURRENCY` width as the download pool). Rejections — e.g. a
+ * 404 on an optional dep — are swallowed here: the promise stays cached in its
+ * rejected state and the caller's per-edge `await fetchPkg(name)` re-surfaces
+ * it, so required deps still throw and optional ones are skipped exactly as in
+ * the single-edge path. Swallowing also stops one bad optional dependency from
+ * aborting the whole wave's batch.
+ */
+/**
+ * Fetch a packument with on-disk ETag revalidation. Reads the cached
+ * `{ etag, packument }` for `(registry, name)`, sends it as `If-None-Match`,
+ * and on a `304 Not Modified` returns the cached body without re-downloading
+ * it; on a `200` it stores the fresh body + ETag and returns it. The cache is
+ * keyed by the registry the name resolves to, so scope-registry overrides never
+ * cross-contaminate. Falls back to a plain fetch when there's no cached entry
+ * or the registry doesn't send an ETag (the 304 fast-path simply never fires).
+ */
+async function fetchPackumentWithDiskCache(name, npmrc, log, signal) {
+    const registry = registryFor(name, npmrc);
+    const disk = getCachedPackument(registry, name);
+    const onRetry = ({ attempt, error, delayMs }) => {
+        log('packument %s: retry %d after %dms (%s)', name, attempt, delayMs, errMsg(error));
+    };
+    const result = await fetchPackumentConditional(name, {
+        npmrc,
+        signal,
+        ifNoneMatch: disk?.etag,
+        onRetry,
+    });
+    if (result.status === 'not-modified' && disk) {
+        log('packument-cache-hit: %s (304, etag %s)', name, disk.etag);
+        return disk.packument;
+    }
+    if (result.status === 'fresh' && result.packument) {
+        if (result.etag)
+            putCachedPackument(registry, name, result.etag, result.packument);
+        return result.packument;
+    }
+    // 304 with no cached body to satisfy it (a stale `If-None-Match` raced a
+    // cache eviction). Re-fetch unconditionally so we always return a body.
+    return fetchPackument(name, { npmrc, signal, onRetry });
+}
+async function prefetchPackuments(names, fetchPkg, signal) {
+    if (names.length === 0)
+        return;
+    let cursor = 0;
+    const concurrency = Math.max(1, Math.min(DEFAULT_CONCURRENCY, names.length));
+    const worker = async () => {
+        while (cursor < names.length) {
+            if (signal?.aborted)
+                return;
+            const name = names[cursor++];
+            try {
+                await fetchPkg(name);
+            }
+            catch {
+                /* cached rejection — the serial placement pass handles it */
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: concurrency }, () => worker()));
+}
 /**
  * Walk the ancestor `node_modules` chain from `requesterPath` upward,
  * looking for a placement of `name` that the requester would resolve
@@ -448,13 +558,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 +587,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 +600,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 +619,37 @@ 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 if ((bytes = getForeignCachedTarball(node.integrity))) {
+        // Second-chance: npm's cacache content store (same SRI key). A user
+        // who has run `npm install` before already has the tarball on disk —
+        // read it instead of the network. Write it through to OUR store so
+        // the next `gjsify install` is a first-class hit even if npm later
+        // prunes its cache.
+        log('npm-cache-hit: %s@%s ← %s', node.name, node.version, node.integrity);
+        putCachedTarball(node.integrity, bytes);
+    }
+    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-cache-fs.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare function gjsifyCacheRoot(kind: string, layoutVersion: string): string;
+/**
+ * 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 declare function atomicWrite(path: string, bytes: Uint8Array | string): void;
+/**
+ * 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 declare function readCacheFile(path: string): Buffer | null;