@vltpkg/cli-sdk 1.5.0 → 1.6.1

package/dist/pack-tarball.js

@@ -3,7 +3,7 @@ import { minimatch } from 'minimatch';
 import { error } from '@vltpkg/error-cause';
 import * as ssri from 'ssri';
 import assert from 'node:assert';
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync, } from 'node:fs';
 import { Spec } from '@vltpkg/spec';
 import { join } from 'node:path';
 import { parse, stringify } from 'polite-json';
@@ -155,7 +155,24 @@ export const buildPackFilter = (manifest, packDir) => {
             }
         }
     }
-    return (path) => {
+    // `files` entries are normalized like npm does: a leading `./` or `/`
+    // and trailing slashes are dropped, empty entries are skipped
+    const files = (manifestWithFiles.files ?? [])
+        .map(pattern => pattern.replace(/^\.?\//, '').replace(/\/+$/, ''))
+        .filter(Boolean);
+    // dirs that only partially match a `files` glob (e.g. `dist/nested` for
+    // `dist/**/*.js`) are descended, unless unreadable: npm's glob expansion
+    // skips those too
+    const isReadableDir = (dir) => {
+        try {
+            readdirSync(join(packDir, dir));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    return (path, entry) => {
         const normalizedPath = path.replace(/^\.\//, '');
         if (path === '.' || normalizedPath === '') {
             return true;
@@ -173,23 +190,16 @@ export const buildPackFilter = (manifest, packDir) => {
         if (hasEmptyFilesField) {
             return false;
         }
-        if (hasFilesField && manifestWithFiles.files) {
-            return manifestWithFiles.files.some((pattern) => {
-                if (pattern.endsWith('/')) {
-                    const dirName = pattern.slice(0, -1);
-                    const globPattern = pattern.replace(/\/$/, '/**');
-                    const matchesDir = normalizedPath === dirName;
-                    const matchesContents = minimatch(normalizedPath, globPattern, { dot: true });
-                    return matchesDir || matchesContents;
-                }
-                const directMatch = minimatch(normalizedPath, pattern, {
-                    dot: true,
-                });
-                const isParentDir = pattern.includes('/') &&
-                    pattern.startsWith(normalizedPath + '/');
-                const isChildOfPattern = minimatch(normalizedPath, pattern + '/**', { dot: true });
-                return directMatch || isParentDir || isChildOfPattern;
-            });
+        if (hasFilesField) {
+            const isDir = 'isDirectory' in entry && entry.isDirectory();
+            return (files.some(pattern => minimatch(normalizedPath, pattern, { dot: true }) ||
+                minimatch(normalizedPath, `${pattern}/**`, { dot: true })) ||
+                (isDir &&
+                    files.some(pattern => minimatch(normalizedPath, pattern, {
+                        dot: true,
+                        partial: true,
+                    })) &&
+                    isReadableDir(normalizedPath)));
         }
         // Ignore-file mode: apply .npmignore or .gitignore deny patterns
         if (ig?.ignores(normalizedPath)) {

package/dist/parse-add-remove-args.js

@@ -2,7 +2,7 @@ import { addKey, asDependency } from '@vltpkg/graph';
 import { joinDepIDTuple, splitDepID } from '@vltpkg/dep-id';
 import { Spec } from '@vltpkg/spec';
 import { isAbsolute, relative, resolve } from 'node:path';
-import { asUnknownSpecPrefix } from "./require-registry.js";
+import { parseSpecArg } from "./require-registry.js";
 const rootDepID = joinDepIDTuple(['file', '.']);
 /**
  * Compute a DepID for the current working directory relative to the project
@@ -77,18 +77,6 @@ const rebaseFileSpec = (spec, importerPath, scurryCwd, specOptions, monorepo) =>
         return spec;
     return Spec.parseArgs(rebasedPath, specOptions);
 };
-/**
- * Parse a positional arg, turning an unknown `name:` prefix into an
- * `ECONFIG` that says how to define it.
- */
-const parseArg = (item, options) => {
-    try {
-        return Spec.parseArgs(item, options);
-    }
-    catch (er) {
-        throw asUnknownSpecPrefix(er);
-    }
-};
 /**
  * Parses the positional arguments into {@link AddImportersDependenciesMap}.
  */
@@ -103,7 +91,7 @@ export const parseAddArgs = (config, scurry, monorepo) => {
     const parsedItems = [];
     let hasFileSpecs = false;
     for (const item of items) {
-        const spec = parseArg(item, specOptions);
+        const spec = parseSpecArg(item, specOptions);
         parsedItems.push({ spec, type });
         if (spec.type === 'file')
             hasFileSpecs = true;

package/dist/query-auth.d.ts

@@ -3,7 +3,8 @@ import type { LoadedConfig } from './config/index.ts';
 /**
  * Returns a {@link GetAuthHeader} implementation that looks up
  * authorization tokens from the local keychain / env (incl.
- * `VLT_TOKEN_<key>` for configured registries), used by
- * network-reliant query selectors, e.g: `:outdated()`.
+ * `VLT_TOKEN` for the default registry and `VLT_TOKEN_<key>` for
+ * configured registries), used by network-reliant query selectors,
+ * e.g: `:outdated()`.
  */
 export declare const createGetAuthHeader: (conf: LoadedConfig) => GetAuthHeader;

package/dist/query-auth.js

@@ -1,11 +1,13 @@
-import { getTokenByURL, registryKeys } from '@vltpkg/registry-client';
+import { defaultRegistryKey, getTokenByURL, registryKeys, } from '@vltpkg/registry-client';
 /**
  * Returns a {@link GetAuthHeader} implementation that looks up
  * authorization tokens from the local keychain / env (incl.
- * `VLT_TOKEN_<key>` for configured registries), used by
- * network-reliant query selectors, e.g: `:outdated()`.
+ * `VLT_TOKEN` for the default registry and `VLT_TOKEN_<key>` for
+ * configured registries), used by network-reliant query selectors,
+ * e.g: `:outdated()`.
  */
 export const createGetAuthHeader = (conf) => {
     const keys = registryKeys(conf.options);
-    return async (url) => getTokenByURL(url, conf.options.identity, keys);
+    const def = defaultRegistryKey(conf.options);
+    return async (url) => getTokenByURL(url, conf.options.identity, keys, def);
 };

package/dist/reload-config.js

@@ -7,5 +7,6 @@ export const reloadConfig = async (folder) => {
     }
     catch { }
     const { Config } = await import("./config/index.js");
-    return Config.load(folder, process.argv, true);
+    // host contexts never switch to the global project
+    return Config.load(folder, process.argv, true, false);
 };

package/dist/require-registry.d.ts

@@ -1,3 +1,5 @@
+import { Spec } from '@vltpkg/spec';
+import type { SpecOptions } from '@vltpkg/spec';
 import type { RegistryCandidate } from './select-registry.ts';
 import type { LoadedConfig } from './config/index.ts';
 /**
@@ -17,6 +19,11 @@ export declare const unknownSpecPrefixError: (prefix: string, spec: string, vali
  * {@link unknownSpecPrefixError}. Other values are returned as is.
  */
 export declare const asUnknownSpecPrefix: (er: unknown) => unknown;
+/**
+ * Parse a positional arg, turning an unknown `name:` prefix into an
+ * `ECONFIG` that says how to define it.
+ */
+export declare const parseSpecArg: (item: string, options: SpecOptions) => Spec;
 /**
  * Install-related commands need the alias that bare specs resolve
  * through (not merely some other configured registry) so packages and

package/dist/require-registry.js

@@ -1,6 +1,6 @@
 import { error } from '@vltpkg/error-cause';
 import { isErrorWithCause, isObject } from '@vltpkg/types';
-import { defaultRegistries, defaultRegistryName } from '@vltpkg/spec';
+import { defaultRegistries, defaultRegistryName, Spec, } from '@vltpkg/spec';
 import { selectRegistry } from "./select-registry.js";
 /**
  * There is no default registry. This is the single message used
@@ -41,6 +41,18 @@ export const asUnknownSpecPrefix = (er) => {
         unknownSpecPrefixError(found.slice(0, -1), spec, validOptions)
         : er;
 };
+/**
+ * Parse a positional arg, turning an unknown `name:` prefix into an
+ * `ECONFIG` that says how to define it.
+ */
+export const parseSpecArg = (item, options) => {
+    try {
+        return Spec.parseArgs(item, options);
+    }
+    catch (er) {
+        throw asUnknownSpecPrefix(er);
+    }
+};
 /**
  * Install-related commands need the alias that bare specs resolve
  * through (not merely some other configured registry) so packages and

package/dist/self-update.d.ts

@@ -0,0 +1,74 @@
+import type { DepID } from '@vltpkg/dep-id';
+import type { Graph } from '@vltpkg/graph';
+import type { LoadedConfig } from './config/index.ts';
+import type { GlobalBins } from './global.ts';
+export type SelfUpdateCase = 'standalone' | 'npm' | 'global-project' | 'bootstrap';
+/** `vlt install -g vlt` that ran, or had nothing to do */
+export type SelfUpdated = {
+    case: SelfUpdateCase;
+    status: 'updated' | 'up-to-date' | 'newer-running' | 'failed';
+    /** running version */
+    from: string;
+    /** resolved version */
+    to: string;
+    /** dir of the updated vlt */
+    dir: string;
+    /** newer-running: dist-tag of the implicit spec */
+    tag?: string;
+    /** bootstrap: the dir that is not writable */
+    notWritable?: string;
+    /** bootstrap: PATH dir whose vlt still runs first */
+    shadowedBy?: string;
+};
+/** vlt can't update this vlt, `message` says how to */
+export type SelfRefused = {
+    status: 'refused';
+    /** running version */
+    from: string;
+    /** dir of the running vlt */
+    dir: string;
+    message: string;
+};
+/** result of `vlt install -g vlt` */
+export type SelfUpdate = SelfUpdated | SelfRefused;
+export type SelfUpdatePlan = {
+    done: SelfUpdate;
+}
+/** caller runs the -g install, then `finish` */
+ | {
+    selfUnwritable: boolean;
+    finish: (global?: GlobalBins) => Promise<SelfUpdated>;
+};
+/** `checksum` of the file written to `dest`, `sha512-<base64>` */
+export type Release = {
+    checksum: string;
+};
+/** download one standalone entry point to `dest` */
+export type FetchRelease = (o: {
+    version: string;
+    target: string;
+    channel?: string;
+    bin: string;
+    dest: string;
+}) => Promise<Release>;
+/** `vlt install -g vlt...`, for the human view */
+export declare const isSelfUpdateArgs: (conf: Pick<LoadedConfig, "command" | "globalRoot" | "positionals">) => boolean;
+/**
+ * `vlt install -g vlt`: update the vlt on the PATH the way it was
+ * installed. Undefined when vlt is not a positional.
+ */
+export declare const selfUpdate: (conf: LoadedConfig, { fetchRelease }?: {
+    fetchRelease?: FetchRelease;
+}) => Promise<SelfUpdatePlan | undefined>;
+/** `vlt uninstall -g vlt` of a vlt that is not a global package */
+export declare const refuseSelfUninstall: (conf: LoadedConfig) => Promise<SelfRefused | undefined>;
+/** store id of the running vlt, when it runs from the global project */
+export declare const runningStoreDep: (root: string) => Promise<DepID | undefined>;
+/**
+ * Record the running vlt's store dir for removal by a later -g
+ * command when the graph no longer has it, and forget listed dirs
+ * the graph has again.
+ */
+export declare const deferSelfRemove: (root: string, graph: Pick<Graph, "nodes">, keep?: DepID) => Promise<void>;
+/** human lines for a self-update */
+export declare const selfUpdateLines: (s: SelfUpdate) => string[];

package/dist/self-update.js

@@ -0,0 +1,401 @@
+import { findCmdShimIfExists } from '@vltpkg/cmd-shim';
+import { isDepID } from '@vltpkg/dep-id';
+import { error } from '@vltpkg/error-cause';
+import { lt, valid } from '@vltpkg/semver';
+import { Spec } from '@vltpkg/spec';
+import { which } from '@vltpkg/which';
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants, existsSync } from 'node:fs';
+import { access, chmod, lstat, readFile, realpath, rename, rm, stat, } from 'node:fs/promises';
+import { basename, dirname, extname, join, relative, resolve, sep, } from 'node:path';
+import { loadPackageJson } from 'package-json-from-dist';
+import { findSelf } from "./global-bin-dir.js";
+import { globalSpec } from "./global.js";
+import { globalWorkspacePath, isInside, samePath, } from "./global-project.js";
+import { readGlobalState, updateGlobalState } from "./global-state.js";
+import { writeInstallReceipt } from "./install-receipt.js";
+import { parseSpecArg } from "./require-registry.js";
+import { prettyPath } from "./shell.js";
+const { version: running } = loadPackageJson(import.meta.filename, process.env.__VLT_INTERNAL_CLI_PACKAGE_JSON);
+const installerLine = 'Re-run the installer to update vlt:\n  curl -fsSL https://install.vlt.sh | bash';
+const writable = (dir) => access(dir, constants.W_OK).then(() => true, () => false);
+// exit 1 without usage: the usage was fine
+const refuse = (self, message) => {
+    process.exitCode = 1;
+    return { status: 'refused', from: running, dir: self.dir, message };
+};
+const isFile = (f) => stat(f).then(s => s.isFile(), () => false);
+const cellars = () => [
+    process.env.HOMEBREW_CELLAR,
+    '/opt/homebrew/Cellar',
+    '/usr/local/Cellar',
+    '/home/linuxbrew/.linuxbrew/Cellar',
+].filter((c) => !!c);
+const whichNpm = async () => {
+    try {
+        const found = await which('npm', { nothrow: true });
+        if (!found)
+            return;
+        const real = await realpath((await findCmdShimIfExists(found))?.[1] ?? found);
+        return basename(real) === 'npm-cli.js' ? real : undefined;
+    }
+    catch { }
+};
+// npm's -g layout: <prefix>/lib/node_modules, win32 <prefix>/node_modules
+const findNpm = async (self) => {
+    const i = self.target.lastIndexOf(`${sep}node_modules${sep}vlt${sep}`);
+    if (i === -1)
+        return;
+    const nm = self.target.slice(0, i) + sep + 'node_modules';
+    const win32 = process.platform === 'win32';
+    const up = dirname(nm);
+    const prefix = win32 ?
+        // vlt.cmd is in the prefix
+        samePath(up, self.dir) && up
+        : basename(up) === 'lib' && dirname(up);
+    if (!prefix)
+        return;
+    const node = dirname(process.execPath);
+    const candidates = [
+        join(nm, 'npm/bin/npm-cli.js'),
+        win32 ?
+            join(node, 'node_modules/npm/bin/npm-cli.js')
+            : join(dirname(node), 'lib/node_modules/npm/bin/npm-cli.js'),
+    ];
+    for (const c of candidates) {
+        if (await isFile(c))
+            return { npmCli: c, prefix };
+    }
+    const npmCli = await whichNpm();
+    return npmCli && { npmCli, prefix };
+};
+const classify = async (self, root) => {
+    // before the receipt: it can outlive the vlt it was written for
+    const g = await realpath(root).catch(() => resolve(root));
+    if (isInside(g, self.target))
+        return { kind: 'global-project' };
+    const { receipt } = self;
+    if (receipt?.data.method === 'standalone') {
+        if (self.standalone)
+            return { kind: 'standalone-receipt', receipt };
+    }
+    else if (receipt) {
+        const npm = receipt.data.method === 'npm' && (await findNpm(self));
+        return npm ?
+            { kind: 'npm', ...npm, receipt }
+            : { kind: 'installer' };
+    }
+    // before npm: a node formula has npm's layout
+    if (cellars().some(c => isInside(c, self.target))) {
+        return { kind: 'homebrew' };
+    }
+    if (self.standalone)
+        return { kind: 'standalone' };
+    const npm = await findNpm(self);
+    return npm ? { kind: 'npm', ...npm } : { kind: 'unknown' };
+};
+const sha512 = async (file) => `sha512-${createHash('sha512')
+    .update(await readFile(file))
+    .digest('base64')}`;
+const safeBin = (b) => /^[a-z0-9][\w.-]*$/i.test(b);
+/** a refusal message, or undefined once replaced */
+const updateStandalone = async (self, receipt, to, fetchRelease) => {
+    const { target, channel, binaries = [] } = receipt.data;
+    if (!fetchRelease || !target)
+        return installerLine;
+    const win32 = process.platform === 'win32';
+    const at = prettyPath(self.dir);
+    // stat().uid is 0 on win32
+    if (!win32 &&
+        (await stat(self.found)).uid === 0 &&
+        process.getuid?.() !== 0) {
+        return `vlt at ${at} is owned by root. Update it the way you installed it, or run this as root.`;
+    }
+    if (!(await writable(self.dir))) {
+        return `vlt at ${at} is not writable. Update it the way you installed it.`;
+    }
+    const ext = extname(self.found).toLowerCase() === '.exe' ? '.exe' : '';
+    const entries = [];
+    for (const bin of new Set(binaries)) {
+        if (bin === 'vlt' || !safeBin(bin))
+            continue;
+        const file = join(self.dir, bin + ext);
+        const st = await lstat(file).catch(() => undefined);
+        // links follow vlt
+        if (st && !st.isSymbolicLink())
+            entries.push({ bin, file });
+    }
+    // last, so a failure part-way leaves a working vlt
+    entries.push({
+        bin: 'vlt',
+        file: join(self.dir, basename(self.found)),
+    });
+    const tmps = [];
+    const cleanup = () => Promise.all(tmps.map(f => rm(f, { force: true })));
+    const ready = [];
+    try {
+        for (const { bin, file } of entries) {
+            // a running vlt.exe.old: the rename below says so
+            if (win32)
+                await rm(`${file}.old`, { force: true }).catch(() => { });
+            // same dir: rename is atomic
+            const dest = join(self.dir, `.${bin}-${to}.tmp`);
+            tmps.push(dest);
+            const { checksum } = await fetchRelease({
+                version: to,
+                target,
+                channel,
+                bin,
+                dest,
+            });
+            const found = await sha512(dest);
+            if (found !== checksum) {
+                throw error(`Checksum mismatch for ${bin} ${to}`, {
+                    code: 'EINTEGRITY',
+                    wanted: checksum,
+                    found,
+                });
+            }
+            await chmod(dest, (await stat(file)).mode & 0o777);
+            ready.push({ file, dest });
+        }
+    }
+    catch (er) {
+        await cleanup();
+        throw er;
+    }
+    // never write into a running file: rename only
+    for (const { file, dest } of ready) {
+        try {
+            if (win32) {
+                // a running .exe can be renamed, not replaced
+                await rename(file, `${file}.old`);
+                await rename(dest, file).catch(async (er) => {
+                    await rename(`${file}.old`, file).catch(() => { });
+                    throw er;
+                });
+            }
+            else {
+                await rename(dest, file);
+            }
+        }
+        catch (cause) {
+            await cleanup();
+            throw error(`Could not replace ${file}. Close other vlt processes and editors, and check permissions.`, { path: file, cause });
+        }
+    }
+};
+const runNpm = (npmCli, prefix, arg) => new Promise((res, rej) => {
+    // stdout to stderr: keeps --view=json parseable
+    const child = spawn(process.execPath, [npmCli, 'install', '--global', '--prefix', prefix, arg], { stdio: ['inherit', 2, 2] });
+    child.on('error', rej);
+    child.on('close', (code) => res(code ?? 1));
+});
+const rewriteReceipt = (receipt, to) => receipt &&
+    writeInstallReceipt(receipt.file, { version: to }).catch(() => { });
+// vlt, vlt@..., a vlt tarball
+const vltArg = /^vlt(@|$)|(^|[/\\:])vlt-\d[^/\\]*\.tgz$/;
+/** `vlt install -g vlt...`, for the human view */
+export const isSelfUpdateArgs = (conf) => conf.command === 'install' &&
+    !!conf.globalRoot &&
+    conf.positionals.some(p => vltArg.test(p));
+/**
+ * `vlt install -g vlt`: update the vlt on the PATH the way it was
+ * installed. Undefined when vlt is not a positional.
+ */
+export const selfUpdate = async (conf, { fetchRelease } = {}) => {
+    const { globalRoot, positionals } = conf;
+    if (!globalRoot || !positionals.length)
+        return;
+    const specs = await Promise.all(positionals.map(p => globalSpec(p, conf)));
+    const [spec] = specs;
+    if (!spec || !specs.some(s => s.name === 'vlt'))
+        return;
+    if (specs.length > 1) {
+        throw error('Update vlt on its own, without other packages', {
+            code: 'EUSAGE',
+            found: positionals.join(' '),
+        });
+    }
+    const self = await findSelf();
+    if (!self) {
+        throw error(`Can't tell which vlt to update: run the vlt on your PATH, not ${process.argv[1] ?? process.execPath}`, { code: 'EUSAGE' });
+    }
+    const owner = await classify(self, globalRoot);
+    const at = prettyPath(self.dir);
+    const foreign = `vlt at ${at} is not managed by vlt or npm. Update it the way you installed it.`;
+    if (owner.kind === 'installer') {
+        return { done: refuse(self, installerLine) };
+    }
+    if (owner.kind === 'homebrew') {
+        return {
+            done: refuse(self, `vlt at ${at} was installed by Homebrew. Run \`brew upgrade vlt\`.`),
+        };
+    }
+    if (owner.kind === 'standalone') {
+        return { done: refuse(self, foreign) };
+    }
+    // npm's node_modules not writable: npm's EACCES says so
+    const bootstrap = (owner.kind === 'npm' || owner.kind === 'unknown') &&
+        !(await writable(self.dir));
+    if (owner.kind === 'unknown' && !bootstrap) {
+        return { done: refuse(self, foreign) };
+    }
+    const raw = String(positionals[0]);
+    const implicit = !parseSpecArg(raw, conf.options).bareSpec;
+    const receipt = 'receipt' in owner ? owner.receipt : undefined;
+    const channel = receipt?.data.channel;
+    const tag = channel ?? conf.options.tag;
+    const { name, version: to } = await conf.options.packageInfo.manifest(implicit && channel ?
+        Spec.parse('vlt', tag, conf.options)
+        : spec);
+    if (name !== 'vlt' || !to) {
+        throw error(`${raw} is not a version of vlt`, {
+            code: 'EUSAGE',
+            found: name,
+        });
+    }
+    const kind = bootstrap ? 'bootstrap'
+        : owner.kind === 'standalone-receipt' ? 'standalone'
+            : owner.kind === 'npm' ? 'npm'
+                : 'global-project';
+    const base = { case: kind, from: running, to, dir: self.dir };
+    if (to === running)
+        return { done: { ...base, status: 'up-to-date' } };
+    // `latest` may lag a new major
+    if (implicit && lt(to, running)) {
+        return { done: { ...base, status: 'newer-running', tag } };
+    }
+    const registry = spec.final.type === 'registry';
+    if (owner.kind === 'standalone-receipt') {
+        // releases are registry versions
+        if (!registry || !valid(to)) {
+            throw error(`${raw} is not a vlt release`, {
+                code: 'EUSAGE',
+                found: raw,
+            });
+        }
+        const refused = await updateStandalone(self, owner.receipt, to, fetchRelease);
+        if (refused)
+            return { done: refuse(self, refused) };
+        await rewriteReceipt(owner.receipt, to);
+        return { done: { ...base, status: 'updated' } };
+    }
+    if (owner.kind === 'npm' && !bootstrap) {
+        const code = await runNpm(owner.npmCli, owner.prefix, registry ? `vlt@${to}` : `vlt@${spec.bareSpec}`);
+        // npm already said why
+        if (code !== 0) {
+            process.exitCode = code;
+            return { done: { ...base, status: 'failed' } };
+        }
+        await rewriteReceipt(receipt, to);
+        return { done: { ...base, status: 'updated' } };
+    }
+    // the ws pins what was resolved
+    if (registry)
+        conf.positionals = [`vlt@${to}`];
+    return {
+        selfUnwritable: bootstrap,
+        finish: async (global) => {
+            const u = {
+                ...base,
+                status: 'updated',
+                dir: global?.binDir ?? self.dir,
+                ...(bootstrap ? { notWritable: self.dir } : {}),
+            };
+            if (bootstrap &&
+                global?.inPath &&
+                global.bins.includes('vlt')) {
+                const now = await which('vlt', { nothrow: true }).catch(() => null);
+                const first = now && dirname(now);
+                if (first &&
+                    !samePath(await realpath(first).catch(() => first), global.binDir)) {
+                    u.shadowedBy = first;
+                }
+            }
+            return u;
+        },
+    };
+};
+/** `vlt uninstall -g vlt` of a vlt that is not a global package */
+export const refuseSelfUninstall = async (conf) => {
+    const { globalRoot, positionals } = conf;
+    if (!globalRoot || !positionals.includes('vlt'))
+        return;
+    const ws = resolve(globalRoot, globalWorkspacePath('vlt'));
+    if (existsSync(resolve(ws, 'package.json')))
+        return;
+    const self = await findSelf();
+    if (!self)
+        return;
+    const { kind } = await classify(self, globalRoot);
+    return refuse(self, kind === 'npm' ?
+        'vlt was installed by npm. Run `npm uninstall -g vlt` to remove it.'
+        : kind === 'homebrew' ?
+            'vlt was installed by Homebrew. Run `brew uninstall vlt` to remove it.'
+            : `vlt at ${prettyPath(self.dir)} is not managed by vlt. Remove it the way you installed it.`);
+};
+/** store id of the running vlt, when it runs from the global project */
+export const runningStoreDep = async (root) => {
+    const script = process.argv[1];
+    if (!script)
+        return;
+    try {
+        const [real, store] = await Promise.all([
+            realpath(script),
+            realpath(resolve(root, 'node_modules/.vlt')),
+        ]);
+        const [id] = relative(store, real).split(sep);
+        return isDepID(id) ? id : undefined;
+    }
+    catch { }
+};
+/**
+ * Record the running vlt's store dir for removal by a later -g
+ * command when the graph no longer has it, and forget listed dirs
+ * the graph has again.
+ */
+export const deferSelfRemove = async (root, graph, keep) => {
+    const store = resolve(await realpath(root), 'node_modules/.vlt');
+    const add = keep && !graph.nodes.has(keep) ? [resolve(store, keep)] : [];
+    const { pendingRemove = [] } = await readGlobalState(root);
+    const kept = pendingRemove.filter(p => {
+        const id = basename(p);
+        return !(isDepID(id) && graph.nodes.has(id));
+    });
+    if (!add.length && kept.length === pendingRemove.length)
+        return;
+    await updateGlobalState(root, s => ({
+        ...s,
+        pendingRemove: [...new Set([...kept, ...add])],
+    }));
+};
+/** human lines for a self-update */
+export const selfUpdateLines = (s) => {
+    if (s.status === 'refused')
+        return [s.message];
+    if (s.status === 'up-to-date') {
+        return [`✅ vlt ${s.to} is already up to date`];
+    }
+    if (s.status === 'newer-running') {
+        return [
+            `ℹ️  vlt ${s.from} is running but "${s.tag}" is ${s.to}; run \`vlt i -g vlt@${s.tag}\` to downgrade`,
+        ];
+    }
+    if (s.status === 'failed')
+        return [];
+    if (s.case === 'bootstrap') {
+        return [
+            `ℹ️  ${prettyPath(s.notWritable ?? s.dir)} is not writable, so vlt ${s.to} was installed as a global package.`,
+            ...(s.shadowedBy ?
+                [
+                    `⚠️  ${prettyPath(s.shadowedBy)} is earlier in your PATH, so \`vlt\` still runs vlt ${s.from}.`,
+                ]
+                : []),
+        ];
+    }
+    return [
+        `⬆️  Updated vlt ${s.from} → ${s.to} in ${prettyPath(s.dir)}${s.case === 'npm' ? ' (via npm)' : ''}`,
+    ];
+};

package/dist/shell-setup/env.d.ts

@@ -0,0 +1,9 @@
+import type { ShellOptions } from '../shell.ts';
+/** `<global-dir>/env`, sourced by sh-family rc files */
+export declare const envFile: (globalDir: string) => string;
+/** `<global-dir>/env.fish`, sourced by fish */
+export declare const envFishFile: (globalDir: string) => string;
+/** sh script adding `dir` to the `PATH` once */
+export declare const renderEnv: (dir: string, o?: ShellOptions) => string;
+/** fish script adding `dir` to the `PATH` of the session */
+export declare const renderEnvFish: (dir: string, o?: ShellOptions) => string;