@vltpkg/package-info 1.0.0-rc.23 → 1.0.0-rc.24

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { PackageJson } from '@vltpkg/package-json';
+import type { PickManifestOptions } from '@vltpkg/pick-manifest';
+import type { RegistryClientOptions, RegistryClientRequestOptions } from '@vltpkg/registry-client';
+import { RegistryClient } from '@vltpkg/registry-client';
+import type { SpecOptions } from '@vltpkg/spec';
+import { Spec } from '@vltpkg/spec';
+import { Pool } from '@vltpkg/tar';
+import type { Integrity, Manifest, Packument } from '@vltpkg/types';
+import { Monorepo } from '@vltpkg/workspaces';
+export declare const delimiter = "~";
+export type Resolution = {
+    resolved: string;
+    integrity?: Integrity;
+    signatures?: Exclude<Manifest['dist'], undefined>['signatures'];
+    spec: Spec;
+};
+export type PackageInfoClientOptions = RegistryClientOptions & SpecOptions & {
+    /** root of the project. Defaults to process.cwd() */
+    projectRoot?: string;
+    /** PackageJson object */
+    packageJson?: PackageJson;
+    monorepo?: Monorepo;
+    /** workspace groups to load, irrelevant if Monorepo provided */
+    'workspace-group'?: string[];
+    /** workspace paths to load, irrelevant if Monorepo provided */
+    workspace?: string[];
+};
+export type PackageInfoClientRequestOptions = PickManifestOptions & RegistryClientRequestOptions & {
+    /** dir to resolve `file://` specifiers against. Defaults to projectRoot. */
+    from?: string;
+};
+export type PackageInfoClientExtractOptions = PackageInfoClientRequestOptions & {
+    integrity?: Integrity;
+    resolved?: string;
+};
+export declare class PackageInfoClient {
+    #private;
+    options: PackageInfoClientOptions;
+    packageJson: PackageJson;
+    monorepo?: Monorepo;
+    get registryClient(): RegistryClient;
+    get tarPool(): Pool;
+    constructor(options?: PackageInfoClientOptions);
+    extract(spec: Spec | string, target: string, options?: PackageInfoClientExtractOptions): Promise<Resolution>;
+    /**
+     * Conditionally return the path to the manifest cache file. The logic
+     * to determine if caching should be skipped aligns with `pickManifest`
+     * and is used to avoid caching manifest results that can be variable.
+     */
+    _manifestCachePath(spec: Spec, options: PackageInfoClientRequestOptions): string | undefined;
+    tarball(spec: Spec | string, options?: PackageInfoClientExtractOptions): Promise<Buffer>;
+    manifest(spec: Spec | string, options?: PackageInfoClientRequestOptions): Promise<Manifest | import("@vltpkg/types").Override<Manifest, import("@vltpkg/types").NormalizedFields>>;
+    packument(spec: Spec | string, options?: PackageInfoClientRequestOptions): Promise<Packument>;
+    resolve(spec: Spec | string, options?: PackageInfoClientRequestOptions): Promise<Resolution>;
+}

package/dist/index.js

@@ -0,0 +1,665 @@
+import { error } from '@vltpkg/error-cause';
+import { clone, resolve as gitResolve, revs } from '@vltpkg/git';
+import { PackageJson } from '@vltpkg/package-json';
+import { pickManifest } from '@vltpkg/pick-manifest';
+import { RegistryClient } from '@vltpkg/registry-client';
+import { Spec } from '@vltpkg/spec';
+import { Pool } from '@vltpkg/tar';
+import { asPackument, isIntegrity } from '@vltpkg/types';
+import ssri from 'ssri';
+import { Monorepo } from '@vltpkg/workspaces';
+import { XDG } from '@vltpkg/xdg';
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rm, stat, symlink, unlink, writeFile, } from 'node:fs/promises';
+import { basename, dirname, resolve as pathResolve, relative, } from 'node:path';
+import { create as tarC } from 'tar';
+import { rename } from "./rename.js";
+const xdg = new XDG('vlt');
+export const delimiter = '~';
+// the maximum duration of a manifest cache file
+const manifestCacheMaxAge = 5 * 60 * 1000;
+export class PackageInfoClient {
+    #registryClient;
+    #projectRoot;
+    #tarPool;
+    options;
+    #resolutions = new Map();
+    packageJson;
+    monorepo;
+    #trustedIntegrities = new Map();
+    #manifestCacheMinAge = Date.now() - manifestCacheMaxAge;
+    #cachePath;
+    get registryClient() {
+        if (!this.#registryClient) {
+            this.#registryClient = new RegistryClient(this.options);
+        }
+        return this.#registryClient;
+    }
+    get tarPool() {
+        if (!this.#tarPool)
+            this.#tarPool = new Pool();
+        return this.#tarPool;
+    }
+    constructor(options = {}) {
+        this.options = options;
+        this.#projectRoot = options.projectRoot || process.cwd();
+        this.packageJson = options.packageJson ?? new PackageJson();
+        const wsLoad = {
+            ...(options.workspace?.length && { paths: options.workspace }),
+            ...(options['workspace-group']?.length && {
+                groups: options['workspace-group'],
+            }),
+        };
+        this.monorepo =
+            options.monorepo ??
+                Monorepo.maybeLoad(this.#projectRoot, {
+                    load: wsLoad,
+                    packageJson: this.packageJson,
+                });
+        this.#cachePath = options.cache ?? xdg.cache();
+        // optionally create its cache directory if it doesn't exist
+        void mkdir(pathResolve(this.#cachePath, 'package-info'), {
+            recursive: true,
+        }).catch(() => { });
+    }
+    async extract(spec, target, options = {}) {
+        if (typeof spec === 'string')
+            spec = Spec.parse(spec, this.options);
+        const { from = this.#projectRoot, integrity, resolved } = options;
+        const f = spec.final;
+        const r = integrity && resolved ?
+            { resolved, integrity, spec }
+            : await this.resolve(spec, options);
+        switch (f.type) {
+            case 'git': {
+                const { gitRemote, gitCommittish, remoteURL, gitSelectorParsed, } = f;
+                if (!remoteURL) {
+                    /* c8 ignore start - Impossible, would throw on the resolve */
+                    if (!gitRemote)
+                        throw this.#resolveError(spec, options, 'no remote on git: specifier');
+                    /* c8 ignore stop */
+                    const { path } = gitSelectorParsed ?? {};
+                    if (path !== undefined) {
+                        // use obvious name because it's in node_modules
+                        const tmp = pathResolve(dirname(target), `.TEMP.${basename(target)}-${randomBytes(6).toString('hex')}`);
+                        await clone(gitRemote, gitCommittish, tmp, { spec });
+                        const src = pathResolve(tmp, path);
+                        await rename(src, target);
+                        // intentionally not awaited
+                        void rm(tmp, { recursive: true, force: true });
+                    }
+                    else {
+                        await clone(gitRemote, gitCommittish, target, { spec });
+                        // intentionally not awaited
+                        void rm(target + '/.git', { recursive: true });
+                    }
+                    return r;
+                }
+                // fallthrough if a remote tarball url present
+            }
+            case 'registry': {
+                const trustIntegrity = this.#trustedIntegrities.get(r.resolved) === r.integrity;
+                const response = await this.registryClient.request(r.resolved, {
+                    integrity: r.integrity,
+                    trustIntegrity,
+                });
+                if (response.statusCode !== 200) {
+                    throw this.#resolveError(spec, options, 'failed to fetch tarball', {
+                        url: r.resolved,
+                        response,
+                    });
+                }
+                // if it's not trusted already, but valid, start trusting
+                if (!trustIntegrity &&
+                    response.checkIntegrity({ spec, url: resolved })) {
+                    this.#trustedIntegrities.set(r.resolved, response.integrity);
+                }
+                try {
+                    await this.tarPool.unpack(response.buffer(), target);
+                }
+                catch (er) {
+                    throw this.#resolveError(spec, options, 'tar unpack failed', { cause: er });
+                }
+                return r;
+            }
+            case 'remote': {
+                const response = await this.registryClient.request(r.resolved);
+                if (response.statusCode !== 200) {
+                    throw this.#resolveError(spec, options, 'failed to fetch remote tarball', {
+                        url: r.resolved,
+                        response,
+                    });
+                }
+                const buf = response.buffer();
+                // Compute integrity for remote/git-with-tarball deps
+                const computed = ssri
+                    .fromData(buf, { algorithms: ['sha512'] })
+                    .toString();
+                if (r.integrity && r.integrity !== computed) {
+                    throw error('Integrity check failure', {
+                        code: 'EINTEGRITY',
+                        spec,
+                        url: r.resolved,
+                        wanted: r.integrity,
+                        found: computed,
+                    });
+                }
+                r.integrity = computed;
+                try {
+                    await this.tarPool.unpack(buf, target);
+                }
+                catch (er) {
+                    throw this.#resolveError(spec, options, 'remote tar unpack failed', { cause: er });
+                }
+                return r;
+            }
+            case 'file': {
+                // if it's a directory, then "extract" means "symlink"
+                const { file } = f;
+                /* c8 ignore start - asserted in resolve() */
+                if (file === undefined)
+                    throw this.#resolveError(spec, options, 'no file path');
+                /* c8 ignore stop */
+                const path = pathResolve(from, file);
+                const st = await stat(path);
+                if (st.isFile()) {
+                    try {
+                        await this.tarPool.unpack(await this.tarball(spec, options), target);
+                    }
+                    catch (er) {
+                        throw this.#resolveError(spec, options, 'tar unpack failed', { cause: er });
+                    }
+                }
+                else if (st.isDirectory()) {
+                    const rel = relative(dirname(target), path);
+                    await symlink(rel, target, 'dir');
+                    /* c8 ignore start */
+                }
+                else {
+                    throw this.#resolveError(spec, options, 'file: specifier does not resolve to directory or tarball');
+                }
+                /* c8 ignore stop */
+                return r;
+            }
+            case 'workspace': {
+                const ws = this.#getWS(spec, options);
+                const rel = relative(dirname(target), ws.fullpath);
+                await symlink(rel, target, 'dir');
+                return r;
+            }
+        }
+    }
+    #getWS(spec, options) {
+        const { workspace } = spec;
+        /* c8 ignore start - asserted in resolve() */
+        if (workspace === undefined)
+            throw this.#resolveError(spec, options, 'no workspace ID');
+        /* c8 ignore stop */
+        if (!this.monorepo) {
+            throw this.#resolveError(spec, options, 'Not in a monorepo, cannot resolve workspace spec');
+        }
+        const ws = this.monorepo.get(workspace);
+        if (!ws) {
+            throw this.#resolveError(spec, options, 'workspace not found', {
+                wanted: workspace,
+            });
+        }
+        return ws;
+    }
+    /**
+     * Return the manifest cache key for a spec and the current options.
+     */
+    #manifestCacheKey(spec, options) {
+        let extra = '';
+        if (options['node-version']) {
+            extra += `${delimiter}node-version:${options['node-version']}`;
+        }
+        if (options.os) {
+            extra += `${delimiter}os:${options.os}`;
+        }
+        if (options.arch) {
+            extra += `${delimiter}arch:${options.arch}`;
+        }
+        return encodeURIComponent(`${spec.registry}${delimiter}${spec}${extra}`);
+    }
+    /**
+     * Conditionally return the path to the manifest cache file. The logic
+     * to determine if caching should be skipped aligns with `pickManifest`
+     * and is used to avoid caching manifest results that can be variable.
+     */
+    _manifestCachePath(spec, options) {
+        if (options.before) {
+            return;
+        }
+        // if the final resolved spec is either a dist tag or something that
+        // matches any range (such as a semver range of `*` or empty string)
+        // then we skip caching
+        const f = spec.final;
+        if (f.distTag || f.range?.isAny) {
+            return;
+        }
+        const key = this.#manifestCacheKey(f, options);
+        return pathResolve(this.#cachePath, 'package-info', key);
+    }
+    async #registryManifestRequest(spec, options) {
+        const { registry, name, registrySpec } = spec.final;
+        /* c8 ignore start */
+        if (!spec.range?.isSingle || !registrySpec) {
+            throw this.#resolveError(spec, options, 'failed to request manifest', { spec });
+        }
+        /* c8 ignore stop */
+        const possibleLeadingChars = ['=', '^', '~', 'v'];
+        const hasLeadingRange = possibleLeadingChars.some(char => registrySpec.startsWith(char));
+        const version = hasLeadingRange ? registrySpec.slice(1) : registrySpec;
+        const pakuURL = new URL(`${name}/${version}`, registry);
+        const response = await this.registryClient.request(pakuURL, {
+            headers: {
+                accept: 'application/json',
+            },
+        });
+        if (response.statusCode !== 200) {
+            throw this.#resolveError(spec, options, 'failed to fetch manifest', {
+                url: pakuURL,
+                response,
+            });
+        }
+        return response.json();
+    }
+    async tarball(spec, options = {}) {
+        if (typeof spec === 'string')
+            spec = Spec.parse(spec, this.options);
+        const f = spec.final;
+        switch (f.type) {
+            case 'registry': {
+                const { dist } = await this.manifest(spec, options);
+                if (!dist)
+                    throw this.#resolveError(spec, options, 'no dist object found in manifest');
+                const { tarball, integrity } = dist;
+                if (!tarball) {
+                    throw this.#resolveError(spec, options, 'no tarball found in manifest.dist');
+                }
+                const trustIntegrity = this.#trustedIntegrities.get(tarball) === integrity;
+                const response = await this.registryClient.request(tarball, {
+                    ...options,
+                    integrity,
+                    trustIntegrity,
+                });
+                if (response.statusCode !== 200) {
+                    throw this.#resolveError(spec, options, 'failed to fetch tarball', { response, url: tarball });
+                }
+                // if we don't already trust it, but it's valid, start trusting it
+                if (!trustIntegrity &&
+                    response.checkIntegrity({ spec, url: tarball })) {
+                    this.#trustedIntegrities.set(tarball, response.integrity);
+                }
+                return response.buffer();
+            }
+            case 'git': {
+                const { remoteURL, gitRemote, gitCommittish, gitSelectorParsed, } = f;
+                const s = spec;
+                if (!remoteURL) {
+                    if (!gitRemote) {
+                        throw this.#resolveError(spec, options, 'no remote on git: specifier');
+                    }
+                    const { path } = gitSelectorParsed ?? {};
+                    return await this.#tmpdir(async (dir) => {
+                        await clone(gitRemote, gitCommittish, dir + '/package', {
+                            spec: s,
+                        });
+                        let cwd = dir;
+                        if (path !== undefined) {
+                            const src = pathResolve(dir, 'package', path);
+                            cwd = dirname(src);
+                            const pkg = pathResolve(cwd, 'package');
+                            if (src !== pkg) {
+                                const rand = randomBytes(6).toString('hex');
+                                // faster than deleting
+                                await rename(pkg, pkg + rand).catch(() => { });
+                                await rename(src, pkg);
+                            }
+                        }
+                        return tarC({ cwd, gzip: true }, ['package']).concat();
+                    });
+                }
+                // fallthrough if remoteURL set
+            }
+            case 'remote': {
+                const { remoteURL } = f;
+                if (!remoteURL) {
+                    throw this.#resolveError(spec, options);
+                }
+                const response = await this.registryClient.request(remoteURL);
+                if (response.statusCode !== 200) {
+                    throw this.#resolveError(spec, options, 'failed to fetch URL', { response, url: remoteURL });
+                }
+                return response.buffer();
+            }
+            case 'file': {
+                const { file } = f;
+                if (file === undefined)
+                    throw this.#resolveError(spec, options, 'no file path');
+                const { from = this.#projectRoot } = options;
+                const path = pathResolve(from, file);
+                const st = await stat(path);
+                if (st.isDirectory()) {
+                    const p = dirname(path);
+                    const b = basename(path);
+                    // TODO: Pack properly, ignore stuff, bundleDeps, etc
+                    return tarC({ cwd: p, gzip: true }, [b]).concat();
+                }
+                return readFile(path);
+            }
+            case 'workspace': {
+                // TODO: Pack properly, ignore stuff, bundleDeps, etc
+                const ws = this.#getWS(spec, options);
+                const p = dirname(ws.fullpath);
+                const b = basename(ws.fullpath);
+                return tarC({ cwd: p, gzip: true }, [b]).concat();
+            }
+        }
+    }
+    async manifest(spec, options = {}) {
+        const { from = this.#projectRoot } = options;
+        if (typeof spec === 'string')
+            spec = Spec.parse(spec, this.options);
+        const f = spec.final;
+        switch (f.type) {
+            case 'registry': {
+                // Check if manifest is cached, if so just return it earlier
+                const cachePath = this._manifestCachePath(spec, options);
+                if (cachePath) {
+                    try {
+                        // Cache file exists, read and return it
+                        const cached = await readFile(cachePath, 'utf8');
+                        const json = JSON.parse(cached);
+                        // retrieve timestamp to check if cache is still valid
+                        const timestamp = json.__VLT_MANIFEST_CACHE_TIMESTAMP;
+                        delete json.__VLT_MANIFEST_CACHE_TIMESTAMP;
+                        // removes the cache file if older than its maximum age
+                        if (timestamp != null &&
+                            timestamp < this.#manifestCacheMinAge) {
+                            void unlink(cachePath).catch(() => { });
+                            throw new Error('manifest cache expired');
+                        }
+                        return json;
+                    }
+                    catch {
+                        // Cache miss, fetch from packument
+                    }
+                }
+                const mani = spec.range?.isSingle ?
+                    await this.#registryManifestRequest(spec, options)
+                    : pickManifest(await this.packument(f, options), spec, options);
+                if (!mani)
+                    throw this.#resolveError(spec, options);
+                const { integrity, tarball } = mani.dist ?? /* c8 ignore next */ {};
+                if (isIntegrity(integrity) && tarball) {
+                    const registryOrigin = new URL(String(f.registry)).origin;
+                    const tgzOrigin = new URL(tarball).origin;
+                    // if it comes from the same origin, trust the integrity
+                    if (tgzOrigin === registryOrigin) {
+                        this.#trustedIntegrities.set(tarball, integrity);
+                    }
+                }
+                // Cache the manifest data
+                if (cachePath) {
+                    const json = JSON.stringify({
+                        ...mani,
+                        // append a timestamp to the manifest so that we can quickly
+                        // check if the cache is still valid when loading it
+                        __VLT_MANIFEST_CACHE_TIMESTAMP: Date.now(),
+                    });
+                    void writeFile(cachePath, json, 'utf8').catch((err) => {
+                        // in case the cache directory doesn't exist
+                        // just create it and retry
+                        if (err instanceof Error &&
+                            'code' in err &&
+                            err.code === 'ENOENT') {
+                            void mkdir(dirname(cachePath), {
+                                recursive: true,
+                            }).then(() => {
+                                void writeFile(cachePath, json, 'utf8');
+                            });
+                        }
+                    });
+                }
+                return mani;
+            }
+            case 'git': {
+                const { gitRemote, gitCommittish, remoteURL, gitSelectorParsed, } = f;
+                if (!remoteURL) {
+                    const s = spec;
+                    if (!gitRemote)
+                        throw this.#resolveError(spec, options, 'no git remote');
+                    return await this.#tmpdir(async (dir) => {
+                        await clone(gitRemote, gitCommittish, dir, { spec: s });
+                        const { path } = gitSelectorParsed ?? {};
+                        const pkgDir = path !== undefined ? pathResolve(dir, path) : dir;
+                        return this.packageJson.read(pkgDir);
+                    });
+                }
+                // fallthrough to remote
+            }
+            case 'remote': {
+                const { remoteURL } = f;
+                if (!remoteURL) {
+                    throw this.#resolveError(spec, options, 'no remoteURL on remote specifier');
+                }
+                const s = spec;
+                return await this.#tmpdir(async (dir) => {
+                    const response = await this.registryClient.request(remoteURL);
+                    if (response.statusCode !== 200) {
+                        throw this.#resolveError(s, options, 'failed to fetch URL', { response, url: remoteURL });
+                    }
+                    const buf = response.buffer();
+                    // Compute integrity for remote/git-with-tarball deps
+                    const computed = ssri
+                        .fromData(buf, { algorithms: ['sha512'] })
+                        .toString();
+                    try {
+                        await this.tarPool.unpack(buf, dir);
+                    }
+                    catch (er) {
+                        throw this.#resolveError(s, options, 'tar unpack failed', { cause: er });
+                    }
+                    // return manifest with computed integrity
+                    const mani = this.packageJson.read(dir);
+                    mani.dist = { integrity: computed };
+                    return mani;
+                });
+            }
+            case 'file': {
+                const { file } = f;
+                if (file === undefined)
+                    throw this.#resolveError(spec, options, 'no file path');
+                const path = pathResolve(from, file);
+                const st = await stat(path);
+                if (st.isDirectory()) {
+                    return this.packageJson.read(path);
+                }
+                const s = spec;
+                return await this.#tmpdir(async (dir) => {
+                    try {
+                        await this.tarPool.unpack(await readFile(path), dir);
+                    }
+                    catch (er) {
+                        throw this.#resolveError(s, options, 'tar unpack failed', { cause: er });
+                    }
+                    return this.packageJson.read(dir);
+                });
+            }
+            case 'workspace': {
+                return this.#getWS(spec, options).manifest;
+            }
+        }
+    }
+    async packument(spec, options = {}) {
+        if (typeof spec === 'string')
+            spec = Spec.parse(spec, this.options);
+        const f = spec.final;
+        switch (f.type) {
+            // RevDoc is the equivalent of a packument for a git repo
+            case 'git': {
+                const { gitRemote } = f;
+                if (!gitRemote) {
+                    throw this.#resolveError(spec, options, 'git remote could not be determined');
+                }
+                const revDoc = await revs(gitRemote, {
+                    cwd: this.options.projectRoot,
+                });
+                if (!revDoc)
+                    throw this.#resolveError(spec, options);
+                return asPackument(revDoc);
+            }
+            // these are all faked packuments
+            case 'file':
+            case 'workspace':
+            case 'remote': {
+                const manifest = await this.manifest(f, options);
+                return {
+                    name: manifest.name ?? '',
+                    'dist-tags': {
+                        latest: manifest.version ?? '',
+                    },
+                    versions: {
+                        [manifest.version ?? '']: manifest,
+                    },
+                };
+            }
+            case 'registry': {
+                const { registry, name } = f;
+                const pakuURL = new URL(name, registry);
+                const response = await this.registryClient.request(pakuURL, {
+                    headers: {
+                        accept: 'application/json',
+                    },
+                });
+                if (response.statusCode !== 200) {
+                    throw this.#resolveError(spec, options, 'failed to fetch packument', {
+                        url: pakuURL,
+                        response,
+                    });
+                }
+                return response.json();
+            }
+        }
+    }
+    async resolve(spec, options = {}) {
+        const memoKey = String(spec);
+        if (typeof spec === 'string')
+            spec = Spec.parse(spec, this.options);
+        const memo = this.#resolutions.get(memoKey);
+        if (memo)
+            return memo;
+        const f = spec.final;
+        switch (f.type) {
+            case 'file': {
+                const { file } = f;
+                if (!file || !f.file) {
+                    throw this.#resolveError(spec, options, 'no path on file: specifier');
+                }
+                const { from = this.#projectRoot } = options;
+                const resolved = pathResolve(from, f.file);
+                const r = { resolved, spec };
+                this.#resolutions.set(memoKey, r);
+                return r;
+            }
+            case 'remote': {
+                const { remoteURL } = f;
+                if (!remoteURL)
+                    throw this.#resolveError(spec, options, 'no URL in remote specifier');
+                const r = { resolved: remoteURL, spec };
+                this.#resolutions.set(memoKey, r);
+                return r;
+            }
+            case 'workspace': {
+                const ws = this.#getWS(spec, options);
+                return {
+                    resolved: ws.fullpath,
+                    spec,
+                };
+            }
+            case 'registry': {
+                const mani = await this.manifest(spec, options);
+                if (mani.dist) {
+                    const { integrity, tarball, signatures } = mani.dist;
+                    if (tarball) {
+                        const r = {
+                            resolved: tarball,
+                            integrity,
+                            signatures,
+                            spec,
+                        };
+                        this.#resolutions.set(memoKey, r);
+                        return r;
+                    }
+                }
+                throw this.#resolveError(spec, options);
+            }
+            case 'git': {
+                const { gitRemote, remoteURL, gitSelectorParsed } = f;
+                if (remoteURL && gitSelectorParsed?.path === undefined) {
+                    // known git host with a tarball download endpoint
+                    const r = { resolved: remoteURL, spec };
+                    this.#resolutions.set(memoKey, r);
+                    return r;
+                }
+                if (!gitRemote) {
+                    throw this.#resolveError(spec, options, 'no remote on git specifier');
+                }
+                const rev = await gitResolve(gitRemote, f.gitCommittish, {
+                    spec,
+                });
+                if (rev) {
+                    const r = {
+                        resolved: `${gitRemote}#${rev.sha}`,
+                        spec,
+                    };
+                    if (gitSelectorParsed) {
+                        r.resolved += Object.entries(gitSelectorParsed)
+                            .filter(([_, v]) => v)
+                            .map(([k, v]) => `::${k}:${v}`)
+                            .join('');
+                    }
+                    this.#resolutions.set(memoKey, r);
+                    return r;
+                }
+                // have to actually clone somewhere
+                const s = spec;
+                return this.#tmpdir(async (tmpdir) => {
+                    const sha = await clone(gitRemote, s.gitCommittish, tmpdir, {
+                        spec: s,
+                    });
+                    const r = {
+                        resolved: `${gitRemote}#${sha}`,
+                        spec: s,
+                    };
+                    this.#resolutions.set(memoKey, r);
+                    return r;
+                });
+            }
+        }
+    }
+    async #tmpdir(fn) {
+        const p = `package-info/${randomBytes(6).toString('hex')}`;
+        const dir = xdg.runtime(p);
+        try {
+            return await fn(dir);
+        }
+        finally {
+            // intentionally do not await
+            void rm(dir, { recursive: true, force: true });
+        }
+    }
+    // error resolving
+    #resolveError(spec, options = {}, message = 'Could not resolve', extra = {}) {
+        const { from = this.#projectRoot } = options;
+        const er = error(message, {
+            code: 'ERESOLVE',
+            spec,
+            from,
+            ...extra,
+        }, this.#resolveError);
+        return er;
+    }
+}

package/dist/rename.d.ts

@@ -0,0 +1,2 @@
+import { rename as fsRename } from 'node:fs/promises';
+export declare const rename: typeof fsRename;

package/dist/rename.js

@@ -0,0 +1,31 @@
+/**
+ * On posix systems, rename is atomic and will clobber anything in its way
+ * However, on Windows, it can fail with the rather unhelpful EPERM error if
+ * the target directory is not removed in time or is currently in use.
+ *
+ * While true atomic semantics is not available on Windows in this case, we can
+ * at least implement the posix overwrite semantics by explicitly removing the
+ * target when this error occurs.
+ *
+ * This is only relevant when renaming *directories*, since files will
+ * generally not raise problems. When/if we rename directories outside of
+ * package-info, this can be moved to its own shared module.
+ * @module
+ */
+const { platform } = process;
+import { rename as fsRename, rm } from 'node:fs/promises';
+export const rename = platform !== 'win32' ? fsRename : (async function (oldPath, newPath) {
+    let retries = 3;
+    const retry = async (er) => {
+        if (retries > 0 &&
+            er.code === 'EPERM') {
+            retries--;
+            await rm(newPath, { recursive: true, force: true });
+            return fsRename(oldPath, newPath).then(() => { }, retry);
+        }
+        else {
+            throw er;
+        }
+    };
+    return fsRename(oldPath, newPath).then(() => { }, retry);
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/package-info",
   "description": "Resolve and fetch package metadata and tarballs",
-  "version": "1.0.0-rc.23",
+  "version": "1.0.0-rc.24",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -12,16 +12,16 @@
     "email": "support@vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/error-cause": "1.0.0-rc.23",
-    "@vltpkg/git": "1.0.0-rc.23",
-    "@vltpkg/package-json": "1.0.0-rc.23",
-    "@vltpkg/pick-manifest": "1.0.0-rc.23",
-    "@vltpkg/registry-client": "1.0.0-rc.23",
-    "@vltpkg/spec": "1.0.0-rc.23",
-    "@vltpkg/tar": "1.0.0-rc.23",
-    "@vltpkg/types": "1.0.0-rc.23",
-    "@vltpkg/workspaces": "1.0.0-rc.23",
-    "@vltpkg/xdg": "1.0.0-rc.23",
+    "@vltpkg/error-cause": "1.0.0-rc.24",
+    "@vltpkg/git": "1.0.0-rc.24",
+    "@vltpkg/package-json": "1.0.0-rc.24",
+    "@vltpkg/pick-manifest": "1.0.0-rc.24",
+    "@vltpkg/registry-client": "1.0.0-rc.24",
+    "@vltpkg/spec": "1.0.0-rc.24",
+    "@vltpkg/tar": "1.0.0-rc.24",
+    "@vltpkg/types": "1.0.0-rc.24",
+    "@vltpkg/workspaces": "1.0.0-rc.24",
+    "@vltpkg/xdg": "1.0.0-rc.24",
     "ssri": "^13.0.0",
     "tar": "^7.5.2"
   },
@@ -30,8 +30,8 @@
     "@types/node": "^22.19.2",
     "@types/pacote": "^11.1.8",
     "@vltpkg/benchmark": "0.0.0",
-    "@vltpkg/cache-unzip": "1.0.0-rc.23",
-    "@vltpkg/vlt-json": "1.0.0-rc.23",
+    "@vltpkg/cache-unzip": "1.0.0-rc.24",
+    "@vltpkg/vlt-json": "1.0.0-rc.24",
     "eslint": "^9.39.1",
     "pacote": "^21.0.4",
     "prettier": "^3.7.4",