@gjsify/cli 0.4.36 → 0.4.37

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

@@ -17,10 +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';
-import { getCachedTarball, putCachedTarball, } from './install-tarball-cache.js';
-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) {
@@ -139,13 +145,7 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps, signal, progr
         const cached = packumentCache.get(name);
         if (cached)
             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));
-            },
-        });
+        const fresh = fetchPackumentWithDiskCache(name, npmrc, log, signal);
         packumentCache.set(name, fresh);
         return fresh;
     };
@@ -159,94 +159,189 @@ async function resolveDeps(specs, npmrc, log, overrides, skipDeps, signal, progr
         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);
-            // 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({
-                        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`);
+                }
+                // 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);
                 }
-                for (const [depName, depRange] of Object.entries(node.optionalDependencies)) {
-                    queue.push({
-                        from: installPath,
-                        name: depName,
-                        range: applyOverride(depName, depRange),
-                        required: false,
-                    });
+                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
@@ -532,6 +627,15 @@ async function extractOne(node, prefix, npmrc, log, signal) {
     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, {

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;

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-tarball-cache.d.ts

@@ -21,3 +21,11 @@ export declare function putCachedTarball(integrity: string | undefined, bytes: U
  */
 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;