@vltpkg/cli-sdk 1.4.0 → 1.6.0

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;

package/dist/shell-setup/env.js

@@ -0,0 +1,25 @@
+import { resolve } from 'node:path';
+import { fishPath, posixPath, shellPathCommand } from "../shell.js";
+/** `<global-dir>/env`, sourced by sh-family rc files */
+export const envFile = (globalDir) => resolve(globalDir, 'env');
+/** `<global-dir>/env.fish`, sourced by fish */
+export const envFishFile = (globalDir) => resolve(globalDir, 'env.fish');
+/** sh script adding `dir` to the `PATH` once */
+export const renderEnv = (dir, o = {}) => [
+    '# vlt global bin dir; sourced from the shell rc file. Edit with `vlt setup --path`.',
+    'case ":$PATH:" in',
+    `  *:${posixPath(dir, o)}:*) ;;`,
+    `  *) ${shellPathCommand('sh', dir, o)} ;;`,
+    'esac',
+    '',
+].join('\n');
+/** fish script adding `dir` to the `PATH` of the session */
+export const renderEnvFish = (dir, o = {}) => {
+    const d = fishPath(dir, o);
+    return [
+        '# vlt global bin dir; sourced from fish config. Edit with `vlt setup --path`.',
+        // session only, and fish_add_path needs fish 3.2
+        `contains -- ${d} $PATH; or set -gx PATH ${d} $PATH`,
+        '',
+    ].join('\n');
+};

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

@@ -0,0 +1,69 @@
+import type { GlobalBins } from '../global.ts';
+import type { Shell, ShellOptions } from '../shell.ts';
+import type { FileAction, FileChange } from './posix.ts';
+import type { WindowsPathChange } from './windows.ts';
+export type { FileAction } from './posix.ts';
+/** whether `vlt setup --path` can edit config for `shell` */
+export declare const canSetupPath: (shell: Shell, platform?: NodeJS.Platform) => boolean;
+export type PathSetupOptions = ShellOptions & {
+    /** holds the env files and backups */
+    globalDir: string;
+    /** dir to add to the `PATH` */
+    dir: string;
+    shell: Shell;
+};
+export type PathSetupPlan = {
+    globalDir: string;
+    dir: string;
+    shell: Shell;
+    changes: FileChange[];
+    /** win32: user Path change, instead of files */
+    registry?: WindowsPathChange;
+    /** win32: env the user Path was read with */
+    env?: NodeJS.ProcessEnv;
+};
+export type PathSetupFile = {
+    file: string;
+    kind: 'env' | 'rc' | 'registry';
+    action: FileAction | 'prepend';
+};
+export type PathSetupResult = {
+    dir: string;
+    shell: Shell;
+    files: PathSetupFile[];
+    backups: string[];
+};
+/** what adding `dir` to the `PATH` of new shells would change */
+export declare const planPathSetup: (o: PathSetupOptions) => Promise<PathSetupPlan>;
+export declare const pathSetupChanged: (plan: PathSetupPlan) => boolean;
+export declare const pathSetupFiles: (plan: PathSetupPlan) => PathSetupFile[];
+/** rc files or the user Path, for display */
+export declare const rcList: (files: PathSetupFile[], home?: string) => string;
+/** write the plan: env files, rc files, user Path, backed up */
+export declare const applyPathSetup: (plan: PathSetupPlan) => Promise<PathSetupResult>;
+/** loads the env file into the current shell (win32: adds `dir`) */
+export declare const sourceCommand: (shell: Shell, globalDir: string, dir: string, o?: ShellOptions) => string;
+export declare const pathSetupLines: (r: PathSetupResult, source: string, home?: string) => string[];
+/** one trimmed answer */
+export declare const ask: (question: string, { input, output, }?: {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}) => Promise<string>;
+export type OfferOptions = ShellOptions & {
+    globalDir: string;
+    yes?: boolean;
+    noModifyPath?: boolean;
+    input?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    output?: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+    /** once, before the first prompt or line */
+    beforeOutput?: () => void;
+};
+/**
+ * After `install -g` linked into a dir not in the `PATH`: offer, once,
+ * in a terminal, to add it to the PATH. Never throws.
+ */
+export declare const offerPathSetup: (g: GlobalBins, o: OfferOptions) => Promise<void>;