@vltpkg/cli-sdk 1.5.0 → 1.6.1

package/dist/global.d.ts

@@ -0,0 +1,78 @@
+import type { DepID } from '@vltpkg/dep-id';
+import type { AddImportersDependenciesMap, Graph, RemoveImportersDependenciesMap } from '@vltpkg/graph';
+import { RollbackRemove } from '@vltpkg/rollback-remove';
+import { Spec } from '@vltpkg/spec';
+import type { PathScurry } from 'path-scurry';
+import type { LoadedConfig } from './config/index.ts';
+import type { GlobalBinDirSource, ResolvedGlobalBinDir } from './global-bin-dir.ts';
+import type { Shell, ShellOptions } from './shell.ts';
+/**
+ * Bins linked by a global install. `conflicts` are names skipped because
+ * another global package or a foreign file owns them (`--force`
+ * overwrites).
+ */
+export type GlobalBins = {
+    binDir: string;
+    source: GlobalBinDirSource;
+    bins: string[];
+    conflicts: string[];
+    inPath: boolean;
+    /** other bin dirs that had links removed */
+    otherDirs: string[];
+    /** self dir passed over as unwritable, when worth saying */
+    notWritable?: string;
+};
+export type LinkGlobalBinsOptions = {
+    projectRoot: string;
+    scurry: PathScurry;
+    force?: boolean;
+    binDir: ResolvedGlobalBinDir;
+    /** tried once when the self dir refuses writes */
+    fallback?: () => Promise<ResolvedGlobalBinDir>;
+};
+export type GlobalAddArgs = {
+    add: AddImportersDependenciesMap;
+    /** ws dirs created by this run, removed if the install fails */
+    created: string[];
+    /** importers to link bins for, undefined = all */
+    importers?: Set<DepID>;
+};
+export type GlobalRemoveArgs = {
+    remove: RemoveImportersDependenciesMap;
+    dirs: string[];
+};
+/** throws `EUSAGE` for options not supported with `--global` */
+export declare const assertGlobalOptions: (conf: LoadedConfig) => void;
+/**
+ * A positional as a named spec, file: paths made absolute. Once per
+ * conf: a nameless spec fetches its manifest.
+ */
+export declare const globalSpec: (item: string, conf: LoadedConfig) => Promise<Spec>;
+/** one workspace per positional, created if missing */
+export declare const parseGlobalAddArgs: (conf: LoadedConfig) => Promise<GlobalAddArgs>;
+/** the workspace of each positional, which must exist */
+export declare const parseGlobalRemoveArgs: (conf: LoadedConfig) => GlobalRemoveArgs;
+/** rm -rf the given workspace dirs */
+export declare const removeGlobalWorkspaces: (dirs: string[]) => Promise<void>;
+/**
+ * Remove bins in `binDir` that link into any of `dirs`.
+ * Returns the removed names, sorted.
+ */
+export declare const unlinkGlobalBins: (binDir: string, dirs: string[], remover?: RollbackRemove) => Promise<string[]>;
+/**
+ * Link the bins of the deps of global workspaces into `opts.binDir`,
+ * after removing the ones they owned there and in other bin dirs used
+ * before. All workspaces when no `importers` given.
+ */
+export declare const linkGlobalBins: (graph: Graph, opts: LinkGlobalBinsOptions, importers?: Set<DepID>) => Promise<GlobalBins>;
+/**
+ * Unlink the bins of the given workspace dirs from `binDir` (default
+ * `<root>/bin`) and other bin dirs used before, and remove them.
+ */
+export declare const removeGlobalPackages: (projectRoot: string, dirs: string[], binDir?: string) => Promise<void>;
+/** whether `dir` is in the `PATH` */
+export declare const isInPath: (dir: string, PATH?: string) => boolean;
+/** human lines about linked bins, with the `PATH` fix when needed */
+export declare const globalBinsLines: (g: GlobalBins, opts?: ShellOptions & {
+    shell?: Shell;
+}) => string[];

package/dist/global.js

@@ -0,0 +1,409 @@
+import { cmdShimIfExists, findCmdShimIfExists, } from '@vltpkg/cmd-shim';
+import { joinDepIDTuple } from '@vltpkg/dep-id';
+import { error } from '@vltpkg/error-cause';
+import { RollbackRemove } from '@vltpkg/rollback-remove';
+import { Spec } from '@vltpkg/spec';
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import { lstat, mkdir, readdir, realpath, rm, stat, symlink, writeFile, } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, delimiter, isAbsolute, relative, resolve, sep, } from 'node:path';
+import { globalBinDir, globalWorkspaceName, globalWorkspacePath, globalWorkspacesDir, isInside, samePath, } from "./global-project.js";
+import { readGlobalState, updateGlobalState } from "./global-state.js";
+import { parseSpecArg } from "./require-registry.js";
+import { detectShell, prettyPath, shellPathCommand, shellRcFile, } from "./shell.js";
+import { canSetupPath } from "./shell-setup/index.js";
+const unsupported = [
+    'workspace',
+    'workspace-group',
+    'lockfile-only',
+];
+/** throws `EUSAGE` for options not supported with `--global` */
+export const assertGlobalOptions = (conf) => {
+    for (const name of unsupported) {
+        const found = conf.values[name];
+        if (found !== undefined && found !== false) {
+            throw error(`--${name} is not supported with --global`, {
+                code: 'EUSAGE',
+                name,
+                found,
+            });
+        }
+    }
+};
+const workspaceId = (path) => joinDepIDTuple(['workspace', path]);
+const specs = new WeakMap();
+/**
+ * A positional as a named spec, file: paths made absolute. Once per
+ * conf: a nameless spec fetches its manifest.
+ */
+export const globalSpec = (item, conf) => {
+    const known = specs.get(conf) ?? new Map();
+    specs.set(conf, known);
+    const spec = known.get(item) ?? namedSpec(item, conf);
+    known.set(item, spec);
+    return spec;
+};
+const namedSpec = async (item, conf) => {
+    const options = conf.options;
+    let spec = parseSpecArg(item, options);
+    if (spec.type === 'file' && spec.file && !isAbsolute(spec.file)) {
+        const file = resolve(process.cwd(), spec.file)
+            .split(sep)
+            .join('/');
+        spec = Spec.parse(spec.name, `file:${file}`, options);
+    }
+    // a bare name gets the default tag, like npm
+    if (spec.type === 'registry' && !spec.bareSpec) {
+        return Spec.parse(spec.name, options.tag, options);
+    }
+    if (spec.name !== '(unknown)')
+        return spec;
+    const { name } = await options.packageInfo.manifest(spec, {
+        from: process.cwd(),
+    });
+    if (!name) {
+        throw error('Could not determine package name', {
+            code: 'EUSAGE',
+            spec,
+        });
+    }
+    return Spec.parse(name, spec.bareSpec, options);
+};
+// `@s+p-ws` -> `@s/p`
+const wsPackageName = (dir) => dir.replace(/-ws$/, '').replace('+', '/');
+/**
+ * The workspace of `name`. Matched by exact case, since the fs may
+ * ignore it but workspace ids don't. `variant` is an installed name
+ * that differs only in case.
+ */
+const findWorkspace = (projectRoot, name) => {
+    const path = globalWorkspacePath(name);
+    const dir = resolve(projectRoot, path);
+    const base = basename(path);
+    const entries = readdirSync(resolve(projectRoot, globalWorkspacesDir));
+    const variant = entries.find(e => e !== base && e.toLowerCase() === base.toLowerCase());
+    return {
+        path,
+        dir,
+        exists: entries.includes(base) &&
+            existsSync(resolve(dir, 'package.json')),
+        variant: variant && wsPackageName(variant),
+    };
+};
+/** one workspace per positional, created if missing */
+export const parseGlobalAddArgs = async (conf) => {
+    const { positionals, projectRoot } = conf;
+    const add = Object.assign(new Map(), { modifiedDependencies: positionals.length > 0 });
+    const created = [];
+    const importers = new Set();
+    try {
+        for (const item of positionals) {
+            const spec = await globalSpec(item, conf);
+            const { path, dir, exists, variant } = findWorkspace(projectRoot, spec.name);
+            if (!exists) {
+                if (variant) {
+                    throw error(`${spec.name} differs only in case from global package ${variant}`, { code: 'EUSAGE', found: spec.name });
+                }
+                await mkdir(dir, { recursive: true });
+                created.push(dir);
+                const ws = {
+                    name: globalWorkspaceName(spec.name),
+                    private: true,
+                };
+                await writeFile(resolve(dir, 'package.json'), JSON.stringify(ws, null, 2) + '\n');
+            }
+            const id = workspaceId(path);
+            importers.add(id);
+            const dep = { spec, type: 'implicit' };
+            add.set(id, new Map([[spec.name, dep]]));
+        }
+    }
+    catch (er) {
+        await removeGlobalWorkspaces(created);
+        throw er;
+    }
+    // reload the monorepo with the new workspaces
+    if (created.length)
+        conf.resetOptions(projectRoot);
+    return {
+        add,
+        created,
+        importers: positionals.length ? importers : undefined,
+    };
+};
+/** the workspace of each positional, which must exist */
+export const parseGlobalRemoveArgs = (conf) => {
+    const { positionals, projectRoot } = conf;
+    if (!positionals.length) {
+        throw error('Missing package name(s) to uninstall', {
+            code: 'EUSAGE',
+        });
+    }
+    const remove = Object.assign(new Map(), { modifiedDependencies: true });
+    const dirs = [];
+    for (const name of positionals) {
+        const { path, dir, exists, variant } = findWorkspace(projectRoot, name);
+        const id = workspaceId(path);
+        if (remove.has(id))
+            continue;
+        if (!exists) {
+            throw error(`${name} is not installed globally`, {
+                code: 'EUSAGE',
+                found: name,
+                ...(variant ? { validOptions: [variant] } : null),
+            });
+        }
+        remove.set(id, new Set([name]));
+        dirs.push(dir);
+    }
+    return { remove, dirs };
+};
+/** rm -rf the given workspace dirs */
+export const removeGlobalWorkspaces = async (dirs) => {
+    await Promise.all(dirs.map(dir => rm(dir, { recursive: true, force: true })));
+};
+const shimExts = ['', '.cmd', '.ps1', '.pwsh'];
+// the files a bin link is made of
+const linkFiles = (link) => process.platform === 'win32' ?
+    shimExts.map(ext => link + ext)
+    : [link];
+const realOr = (p) => realpath(p).catch(() => p);
+/**
+ * Remove bins in `binDir` that link into any of `dirs`.
+ * Returns the removed names, sorted.
+ */
+export const unlinkGlobalBins = async (binDir, dirs, remover) => {
+    const entries = await readdir(binDir, {
+        withFileTypes: true,
+    }).catch(() => []);
+    const names = new Set();
+    for (const e of entries) {
+        const name = e.name.replace(/\.(cmd|ps1|pwsh)$/i, '');
+        // never read plain files, they may be big binaries
+        if (name !== e.name || e.isSymbolicLink())
+            names.add(name);
+    }
+    // links may use either spelling of a symlinked dir
+    const roots = [...dirs, ...(await Promise.all(dirs.map(realOr)))];
+    const removed = [];
+    for (const name of names) {
+        const link = resolve(binDir, name);
+        const found = await findCmdShimIfExists(link);
+        if (!found || !roots.some(dir => isInside(dir, found[1])))
+            continue;
+        await Promise.all(linkFiles(link).map(f => remover ? remover.rm(f) : rm(f, { force: true })));
+        removed.push(name);
+    }
+    return removed.sort((a, b) => a.localeCompare(b, 'en'));
+};
+const exists = async (link) => (await Promise.all(linkFiles(link).map(f => lstat(f).then(() => true, () => false)))).some(Boolean);
+// bin names from a lockfile are not re-validated
+const safeBin = (bin) => !!bin &&
+    bin === basename(bin) &&
+    !bin.includes('\\') &&
+    bin !== '.' &&
+    bin !== '..';
+const sorted = (s) => [...s].sort((a, b) => a.localeCompare(b, 'en'));
+const dedupe = (dirs) => dirs.filter((d, i) => dirs.findIndex(x => samePath(x, d)) === i);
+// recorded dirs and `<root>/bin`, but not `current`
+const otherBinDirs = async (root, current, state) => {
+    const g = await realpath(globalBinDir(root)).catch(() => undefined);
+    return dedupe([...(state.binDirs ?? []), ...(g ? [g] : [])]).filter(d => !samePath(d, current));
+};
+const isDir = (d) => stat(d).then(s => s.isDirectory(), () => false);
+const isPermError = (er) => er instanceof Error &&
+    /^(EACCES|EPERM)$/.test(String(er.code));
+// --force in a shared dir: only links and shims, never plain files
+// (other tools' binaries) or the running vlt or node
+const replaceable = async (link, keep) => {
+    if (process.platform !== 'win32' &&
+        !(await lstat(link)).isSymbolicLink()) {
+        return false;
+    }
+    const found = await findCmdShimIfExists(link);
+    if (!found)
+        return false;
+    const to = await realOr(found[1]);
+    return !keep.some(k => samePath(k, to));
+};
+const linkBins = async (graph, opts, importers) => {
+    const { projectRoot, scurry, force } = opts;
+    const { dir: binDir, source } = opts.binDir;
+    const state = await readGlobalState(projectRoot);
+    const targets = [...graph.importers]
+        .filter(i => i !== graph.mainImporter &&
+        (!importers || importers.has(i.id)))
+        .sort((a, b) => a.location.localeCompare(b.location, 'en'));
+    const owned = importers ?
+        targets.map(i => i.resolvedLocation(scurry))
+        : [resolve(projectRoot, globalWorkspacesDir)];
+    const keep = force && source !== 'global-dir' ?
+        await Promise.all([process.execPath, ...process.argv.slice(1, 2)].map(realOr))
+        : undefined;
+    const remover = new RollbackRemove();
+    const bins = new Set();
+    const conflicts = new Set();
+    const otherDirs = [];
+    const created = [];
+    try {
+        await unlinkGlobalBins(binDir, owned, remover);
+        for (const d of await otherBinDirs(projectRoot, binDir, state)) {
+            // best effort, an old dir may be gone or read-only
+            const removed = await unlinkGlobalBins(d, owned, remover).catch(() => []);
+            if (removed.length)
+                otherDirs.push(d);
+        }
+        await mkdir(binDir, { recursive: true });
+        for (const importer of targets) {
+            // canonical, like binDir: short relative links
+            const nm = await realOr(importer.nodeModules(scurry));
+            for (const edge of importer.edgesOut.values()) {
+                for (const [bin, path] of Object.entries(edge.to?.bins ?? {})) {
+                    if (!safeBin(bin))
+                        continue;
+                    const target = resolve(nm, edge.spec.name, path);
+                    // win32 shims need the target, posix links may dangle
+                    const win32 = process.platform === 'win32';
+                    if (win32 && !(await stat(target).catch(() => false))) {
+                        continue;
+                    }
+                    const link = resolve(binDir, bin);
+                    if ((await exists(link)) &&
+                        (!force || (keep && !(await replaceable(link, keep))))) {
+                        conflicts.add(bin);
+                        continue;
+                    }
+                    if (win32) {
+                        created.push(link);
+                        await cmdShimIfExists(target, link, remover);
+                    }
+                    else {
+                        await remover.rm(link);
+                        // already moved aside, so ours from this run (--force)
+                        await rm(link, { force: true });
+                        created.push(link);
+                        await symlink(relative(binDir, target), link);
+                    }
+                    bins.add(bin);
+                }
+            }
+        }
+    }
+    catch (er) {
+        // the remover only restores what it moved aside
+        await Promise.all(created.flatMap(linkFiles).map(f => rm(f, { force: true })));
+        await remover.rollback();
+        throw er;
+    }
+    remover.confirm();
+    return {
+        binDir: opts.binDir,
+        state,
+        bins: sorted(bins),
+        conflicts: sorted(conflicts),
+        otherDirs,
+    };
+};
+// after linking, so a failed write never triggers the fallback
+const recordBinDir = async (projectRoot, { binDir, state, bins, conflicts, otherDirs }) => {
+    const { dir, source, inPath, notWritable } = binDir;
+    // local-bin notice once, global-dir reason with every PATH warning
+    const shown = (bins.length > 0 || conflicts.length > 0) &&
+        (source === 'global-dir' || !state.localBinNoticed);
+    const why = shown ? notWritable : undefined;
+    const notice = !!why && source === 'local-bin';
+    const recorded = [];
+    for (const d of state.binDirs ?? []) {
+        if (await isDir(d))
+            recorded.push(d);
+    }
+    await updateGlobalState(projectRoot, s => ({
+        ...s,
+        binDirs: dedupe([...recorded, dir]),
+        ...(notice ? { localBinNoticed: true } : {}),
+    }));
+    return {
+        binDir: dir,
+        source,
+        bins,
+        conflicts,
+        inPath,
+        otherDirs,
+        ...(why ? { notWritable: why } : {}),
+    };
+};
+/**
+ * Link the bins of the deps of global workspaces into `opts.binDir`,
+ * after removing the ones they owned there and in other bin dirs used
+ * before. All workspaces when no `importers` given.
+ */
+export const linkGlobalBins = async (graph, opts, importers) => {
+    let linked;
+    try {
+        linked = await linkBins(graph, opts, importers);
+    }
+    catch (er) {
+        const { binDir, fallback } = opts;
+        // access(W_OK) can pass where writes fail: win32, macOS TCC
+        if (binDir.source !== 'self' || !fallback || !isPermError(er)) {
+            throw er;
+        }
+        linked = await linkBins(graph, { ...opts, binDir: await fallback() }, importers);
+    }
+    return recordBinDir(opts.projectRoot, linked);
+};
+/**
+ * Unlink the bins of the given workspace dirs from `binDir` (default
+ * `<root>/bin`) and other bin dirs used before, and remove them.
+ */
+export const removeGlobalPackages = async (projectRoot, dirs, binDir) => {
+    const current = binDir ?? globalBinDir(projectRoot);
+    await unlinkGlobalBins(current, dirs);
+    const state = await readGlobalState(projectRoot);
+    for (const d of await otherBinDirs(projectRoot, current, state)) {
+        await unlinkGlobalBins(d, dirs).catch(() => []);
+    }
+    await removeGlobalWorkspaces(dirs);
+};
+/** whether `dir` is in the `PATH` */
+export const isInPath = (dir, PATH = process.env.PATH ?? '') => PATH.split(delimiter).some(p => !!p && samePath(p, dir));
+// bin dirs are canonical, home may not be
+const homeOf = (dir, home, win32) => {
+    if (prettyPath(dir, home, win32) !== dir)
+        return home;
+    try {
+        return realpathSync.native(home);
+    }
+    catch {
+        return home;
+    }
+};
+/** human lines about linked bins, with the `PATH` fix when needed */
+export const globalBinsLines = (g, opts = {}) => {
+    const { shell = detectShell(opts.env, opts.platform), platform = process.platform, } = opts;
+    const win32 = platform === 'win32';
+    const home = homeOf(g.binDir, opts.home ?? homedir(), win32);
+    const pretty = (p) => prettyPath(p, home, win32);
+    const dir = pretty(g.binDir);
+    const lines = [];
+    if (g.notWritable) {
+        lines.push(`ℹ️  Using ${dir} because ${pretty(g.notWritable)} is not writable.`);
+    }
+    if (g.bins.length) {
+        lines.push(`🔗 Linked ${g.bins.join(', ')} in ${dir}`);
+    }
+    if (g.conflicts.length) {
+        lines.push(`⚠️  Skipped ${g.conflicts.join(', ')}: already in ${dir} (use --force to overwrite)`);
+    }
+    if (!g.inPath && (g.bins.length || g.conflicts.length)) {
+        const rc = shellRcFile(shell, opts);
+        const what = g.bins.length ? g.bins.join(', ') : 'global bins';
+        const fix = canSetupPath(shell, platform) ?
+            'Run `vlt setup --path` to add it'
+            : 'Set --global-bin-dir to a folder on your PATH';
+        lines.push(
+        // a paragraph of its own: the install offer follows it
+        '', `⚠️  ${dir} is not on your PATH, so ${what} can't be run yet.`, `   ${fix}, or ${rc ? `add this line to ${rc}` : 'run'}:`, `     ${shellPathCommand(shell, g.binDir, { ...opts, home })}`);
+    }
+    return lines;
+};

package/dist/index.js

@@ -1,5 +1,6 @@
 import { format } from 'node:util';
 import { asRootError, findRootError } from '@vltpkg/output/error';
+import { isError } from '@vltpkg/types';
 import { setVltJsonOnly } from '@vltpkg/workspaces';
 import { loadPackageJson } from 'package-json-from-dist';
 import { getSortedCliOptions, getSortedKeys, } from "./config/definition.js";
@@ -15,7 +16,7 @@ const loadVlt = async (cwd, argv) => {
     catch (e) {
         const code = findRootError(e, { code: 'ECONFIG' }) ? 'ECONFIG' : 'JACKSPEAK';
         const err = asRootError(e, { code });
-        const { found, path, wanted, name } = err.cause;
+        const { found, path, wanted, name, cause } = err.cause;
         const isConfigFile = typeof path === 'string';
         const msg = isConfigFile ? `Problem in Config File ${path}`
             : code === 'ECONFIG' ? 'Config Error'
@@ -32,6 +33,9 @@ const loadVlt = async (cwd, argv) => {
         }
         if (wanted)
             stderr(indent(`Wanted: ${format(wanted)}`));
+        // eg the global project can't be created
+        if (isError(cause))
+            stderr(indent(`Cause: ${cause.message}`));
         if (validOptions) {
             stderr(indent('Valid Options:'));
             stderr(indent(validOptions.join('\n'), 4));
@@ -54,7 +58,8 @@ const run = async () => {
     setVltJsonOnly(vlt.command === 'ci');
     const { monorepo } = vlt.options;
     // Infer the workspace by being in that directory.
-    if (vlt.get('workspace') === undefined) {
+    // Not for the global project, cwd is unrelated to it.
+    if (vlt.get('workspace') === undefined && !vlt.globalRoot) {
         const ws = monorepo?.get(cwd);
         if (ws) {
             vlt.values.workspace = [ws.path];

package/dist/install-receipt.d.ts

@@ -0,0 +1,40 @@
+export declare const receiptName = "install-receipt.json";
+/**
+ * Written by the official installer, in vlt's config dir or next to
+ * (or one dir above) the `vlt` it installed. vlt only updates
+ * `version` and `installedAt`.
+ */
+export type ReceiptData = {
+    receiptVersion: 1;
+    /** 'npm' | 'standalone', anything else is a newer installer */
+    method: string;
+    /** absolute dir holding the entry points */
+    binDir: string;
+    installer?: {
+        name?: string;
+        version?: string;
+    };
+    version?: string;
+    /** dist-tag or version asked for */
+    channel?: string;
+    /** `<os>-<arch>[-<libc>]` of a standalone build */
+    target?: string;
+    binaries?: string[];
+    /** rc files the installer edited */
+    modifiedPath?: string[];
+    installedAt?: string;
+};
+export type InstallReceipt = {
+    file: string;
+    data: ReceiptData;
+};
+/**
+ * The receipt covering the `vlt` found at `found`: valid, and its
+ * `binDir` is the dir of `found`.
+ */
+export declare const readInstallReceipt: (found: string, configDir?: string) => Promise<InstallReceipt | undefined>;
+/** set `version` and `installedAt`, keeping all other fields */
+export declare const writeInstallReceipt: (file: string, update: {
+    version: string;
+    installedAt?: string;
+}) => Promise<void>;

package/dist/install-receipt.js

@@ -0,0 +1,69 @@
+import { error } from '@vltpkg/error-cause';
+import { isObject } from '@vltpkg/types';
+import { XDG } from '@vltpkg/xdg';
+import { readFile, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { samePath } from "./global-project.js";
+import { writeJsonAtomic } from "./global-state.js";
+const xdg = new XDG('vlt');
+export const receiptName = 'install-receipt.json';
+const isStr = (v) => typeof v === 'string';
+const optStr = (v) => v === undefined || isStr(v);
+const optStrs = (v) => v === undefined || (Array.isArray(v) && v.every(isStr));
+const isReceipt = (d) => isObject(d) &&
+    d.receiptVersion === 1 &&
+    isStr(d.method) &&
+    !!d.method &&
+    isStr(d.binDir) &&
+    isAbsolute(d.binDir) &&
+    (d.installer === undefined ||
+        (isObject(d.installer) &&
+            optStr(d.installer.name) &&
+            optStr(d.installer.version))) &&
+    optStr(d.version) &&
+    optStr(d.channel) &&
+    optStr(d.target) &&
+    optStrs(d.binaries) &&
+    optStrs(d.modifiedPath) &&
+    optStr(d.installedAt);
+/**
+ * The receipt covering the `vlt` found at `found`: valid, and its
+ * `binDir` is the dir of `found`.
+ */
+export const readInstallReceipt = async (found, configDir = xdg.config()) => {
+    const dir = dirname(found);
+    const real = await realpath(dir).catch(() => undefined);
+    if (!real)
+        return;
+    for (const file of [
+        resolve(configDir, receiptName),
+        resolve(dir, receiptName),
+        resolve(dir, '..', receiptName),
+    ]) {
+        try {
+            const data = JSON.parse(await readFile(file, 'utf8'));
+            if (isReceipt(data) &&
+                samePath(await realpath(data.binDir), real))
+                return { file, data };
+        }
+        catch { }
+    }
+};
+/** set `version` and `installedAt`, keeping all other fields */
+export const writeInstallReceipt = async (file, update) => {
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (cause) {
+        throw error('Invalid install receipt', { path: file, cause });
+    }
+    if (!isReceipt(raw)) {
+        throw error('Invalid install receipt', { path: file });
+    }
+    await writeJsonAtomic(file, {
+        ...raw,
+        version: update.version,
+        installedAt: update.installedAt ?? new Date().toISOString(),
+    });
+};

package/dist/output.js

@@ -1,6 +1,9 @@
+import { error } from '@vltpkg/error-cause';
 import { formatWithOptions, styleText as utilStyleText, } from 'node:util';
 import { createSupportsColor } from 'supports-color';
 import { defaultView } from "./config/definition.js";
+import { globalCommands } from "./global-project.js";
+import { sweepPendingRemove } from "./global-state.js";
 import { printErr, formatOptions } from "./print-err.js";
 import { hasConfiguredRegistry, hasNpmRegistry, missingNpmRegistryError, missingRegistryError, } from "./require-registry.js";
 import { isLazyView, isViewClass, loadLazyView } from "./view.js";
@@ -158,6 +161,14 @@ export const outputCommand = async (cliCommand, conf, { start, vltVersion } = {
     const telemetryEnabled = conf.values.telemetry;
     const commandName = conf.command;
     try {
+        // explicit only: `global` in the user config is ignored here
+        if (conf.explicit.global && !conf.globalRoot) {
+            throw error(`\`vlt ${conf.command}\` does not support --global`, {
+                code: 'EUSAGE',
+                found: conf.command,
+                validOptions: [...globalCommands],
+            });
+        }
         // checked here rather than in run() so that the missing-registry
         // error is rendered, tracked and exited like any other command
         // error, and so that the `--help` return above still works when
@@ -168,6 +179,8 @@ export const outputCommand = async (cliCommand, conf, { start, vltVersion } = {
         if (needsNpmRegistry && !hasNpmRegistry(conf)) {
             throw missingNpmRegistryError(conf.options['default-registry-alias']);
         }
+        if (conf.globalRoot)
+            await sweepPendingRemove(conf.globalRoot);
         const output = await onDone(await command(conf));
         stopRequestLog();
         const duration_ms = Date.now() - start;

package/dist/pack-tarball.d.ts

@@ -1,4 +1,6 @@
 import type { NormalizedManifest } from '@vltpkg/types';
+import type { Stats } from 'node:fs';
+import type { ReadEntry } from 'tar';
 import type { LoadedConfig } from './config/index.ts';
 export type PackTarballResult = {
     name: string;
@@ -27,7 +29,7 @@ export type PackTarballResult = {
  * .npmrc, vlt.json, etc.) are excluded and always-included files (package.json,
  * README, LICENSE, etc.) are included.
  */
-export declare const buildPackFilter: (manifest: NormalizedManifest, packDir: string) => ((path: string) => boolean);
+export declare const buildPackFilter: (manifest: NormalizedManifest, packDir: string) => ((path: string, entry: Stats | ReadEntry) => boolean);
 /**
  * Create a tarball from a package directory
  * @param {NormalizedManifest} manifest - The manifest of the package to pack