@vltpkg/cli-sdk 1.5.0 → 1.6.1

package/dist/config/index.js

@@ -28,13 +28,15 @@ import { cloneAvailable } from '@vltpkg/tar/clonefile';
 import { resetCaches } from '@vltpkg/dep-id';
 import { getOptions } from '@vltpkg/spec';
 import { assertRecordStringString, assertRecordStringT, isObject, isRecordStringString, } from '@vltpkg/types';
-import { find, load, reload, save } from '@vltpkg/vlt-json';
-import { Monorepo } from '@vltpkg/workspaces';
+import { find, load, reload, save, unload } from '@vltpkg/vlt-json';
+import { Monorepo, workspaceCache } from '@vltpkg/workspaces';
 import { readFile, rm, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, resolve } from 'node:path';
 import { PathScurry } from 'path-scurry';
 import { commands, definition, defaultValues, getCommand, isRecordField, recordFields, storeLinkers, } from "./definition.js";
 import { merge } from "./merge.js";
+import { ensureGlobalProject, globalCommands, } from "../global-project.js";
 import { cloneLayer, mergeLayers } from "./merge-layers.js";
 import { assertSpecAliases } from "./spec-aliases.js";
 export { commands, definition, isRecordField, recordFields, };
@@ -117,6 +119,8 @@ export const recordsToPairs = (obj) => {
 const kRecord = Symbol('parsed key=value record');
 // jackspeak's env var name for a field
 const envKey = (k) => `VLT_${k.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}`;
+// `~` and `~/x` (shells leave `--opt=~/x` alone)
+const expandHome = (p) => p.replace(/^~(?=$|[\\/])/, homedir());
 // `parse()` writes every resolved value to `VLT_*`, so a nested vlt
 // can't tell inherited env from env set for it. this holds the
 // parent's explicit values and the `VLT_*` env it wrote.
@@ -171,7 +175,7 @@ export class Config {
             return this.#options;
         const scurry = new PathScurry(this.projectRoot);
         const packageJson = new PackageJson();
-        const asRecords = pairsToRecords(this.parse().values);
+        const { path: _, ...asRecords } = pairsToRecords(this.parse().values);
         const extras = {
             projectRoot: this.projectRoot,
             signal: this.#abort.signal,
@@ -214,6 +218,8 @@ export class Config {
         this.projectRoot = projectRoot;
         this.#options = undefined;
         resetCaches();
+        // cached manifests belong to the old packageJson
+        workspaceCache.clear();
     }
     // memoized options() getter value
     #options;
@@ -240,6 +246,28 @@ export class Config {
      * `~/projects/xyz`, then the highest dir it will check is `~/projects`
      */
     projectRoot;
+    /**
+     * Global project root, set when `--global` switched to it.
+     */
+    globalRoot;
+    /**
+     * `--global-bin-dir` from cli, env or user config, set with
+     * `globalRoot`.
+     */
+    globalBinDir;
+    // the global project of the `setup` wizard, not switched to
+    #setupGlobal;
+    /**
+     * The global project (`--global-dir`, `--global-bin-dir`: cli > env >
+     * user config, never a project `vlt.json`): the one switched to by
+     * `--global`, or the one `vlt setup` offers PATH setup for.
+     */
+    globalProject() {
+        if (this.globalRoot) {
+            return { root: this.globalRoot, binDir: this.globalBinDir };
+        }
+        return this.#setupGlobal;
+    }
     /**
      * `Record<alias, canonical name>` to dereference command aliases.
      */
@@ -268,6 +296,12 @@ export class Config {
             !storeLinkers.includes(badLinker);
         if (fixLinker)
             process.env.VLT_STORE_LINKER = 'unpack';
+        // an opt-out of dotfile edits: any value but 0 (or empty) is set
+        const noModifyPath = process.env.VLT_NO_MODIFY_PATH;
+        if (noModifyPath !== undefined) {
+            process.env.VLT_NO_MODIFY_PATH =
+                noModifyPath === '' || noModifyPath === '0' ? '0' : '1';
+        }
         const envKeys = Object.keys(defaultValues).filter(k => process.env[envKey(k)] !== undefined);
         const parent = parentEnv();
         // file layer values, before env replaces them
@@ -333,7 +367,27 @@ export class Config {
         if (cmdOrFallback !== 'config') {
             assertSpecAliases(pairsToRecords(p.values));
         }
+        // a project vlt.json global-bin-dir must not reach a nested vlt -g
+        const binDirKey = envKey('global-bin-dir');
+        const keepBinDir = !this.globalRoot && !cliKeys.includes('global-bin-dir');
+        const binDirEnv = process.env[binDirKey];
         this.jack.writeEnv(p);
+        // scripts and nested vlt act on their own project
+        delete process.env[envKey('global')];
+        // but use the same global dir, even from another cwd
+        if (this.globalRoot) {
+            process.env[envKey('global-dir')] = this.globalRoot;
+            if (this.globalBinDir)
+                process.env[binDirKey] = this.globalBinDir;
+            else
+                delete process.env[binDirKey];
+        }
+        else if (keepBinDir) {
+            if (binDirEnv === undefined)
+                delete process.env[binDirKey];
+            else
+                process.env[binDirKey] = binDirEnv;
+        }
         process.env[kParentEnv] = JSON.stringify({
             explicit,
             env: Object.fromEntries(Object.keys(defaultValues).flatMap(k => {
@@ -641,13 +695,99 @@ export class Config {
     /**
      * Find the local config file and load both it and the user-level config in
      * the XDG config home.
+     *
+     * When `args` select a `--global` command, the global project is used
+     * instead of the current one.
      */
-    async loadConfigFile() {
+    async loadConfigFile(args) {
         await this.#maybeLoadConfigFile('user');
+        const g = args && this.#globalProject(args);
+        if (g?.switch) {
+            const { root } = g;
+            try {
+                ensureGlobalProject(root);
+            }
+            catch (cause) {
+                throw error('Could not create the global project', {
+                    code: 'ECONFIG',
+                    found: root,
+                    cause,
+                });
+            }
+            this.globalBinDir = g.binDir;
+            unload('project');
+            this.globalRoot = this.projectRoot = root;
+        }
+        else if (g) {
+            this.#setupGlobal = { root: g.root, binDir: g.binDir };
+        }
         this.projectRoot = dirname(find('project', this.projectRoot));
         await this.#maybeLoadConfigFile('project');
         return this;
     }
+    // global project if `args` run a global command with --global, or
+    // `setup`. cli > env > user config, project config is not loaded yet.
+    // `switch`: use it as the project (not for the setup wizard)
+    #globalProject(args) {
+        const { values, positionals } = this.jack.parseRaw(args);
+        const cmd = getCommand(positionals[0]);
+        if (values.help || !cmd)
+            return;
+        // `setup --path` acts on the global project, the wizard offers to
+        const setup = cmd === 'setup';
+        if (!setup && !globalCommands.has(cmd))
+            return;
+        if (!setup) {
+            const env = process.env[envKey('global')];
+            const global = values.global ??
+                (env !== undefined ?
+                    env === '1'
+                    : this.#defaults().global === true);
+            if (!global)
+                return;
+        }
+        return {
+            root: this.#globalDir(values['global-dir']),
+            binDir: this.#globalBinDir(args),
+            switch: !setup || values.path === true,
+        };
+    }
+    #globalDir(cli) {
+        // empty means unset, never the cwd
+        const dir = cli || process.env[envKey('global-dir')];
+        if (dir)
+            return resolve(expandHome(dir));
+        const user = expandHome(String(this.#defaults()['global-dir'] || defaultValues['global-dir']));
+        // would differ per cwd
+        if (!isAbsolute(user)) {
+            throw error('global-dir in the user config must be absolute', {
+                code: 'ECONFIG',
+                found: user,
+            });
+        }
+        // normalize separators (`~/g` on win32)
+        return resolve(user);
+    }
+    // cli > env > user config, like `#globalProject`
+    #globalBinDir(args) {
+        const { values } = this.jack.parseRaw(args);
+        // empty means unset
+        const dir = values['global-bin-dir'] ||
+            process.env[envKey('global-bin-dir')];
+        if (dir)
+            return resolve(expandHome(dir));
+        const user = this.#defaults()['global-bin-dir'];
+        if (typeof user !== 'string' || !user)
+            return;
+        const p = expandHome(user);
+        if (!isAbsolute(p)) {
+            throw error('global-bin-dir in the user config must be absolute', {
+                code: 'ECONFIG',
+                found: p,
+            });
+        }
+        return resolve(p);
+    }
     /**
      * Clear cached config values to force re-reading from updated files.
      * @internal
@@ -694,11 +834,13 @@ export class Config {
      * only used in tests, resets the memoization
      * @internal
      */
-    reload = false) {
+    reload = false, 
+    /** switch to the global project on `--global` */
+    allowGlobal = true) {
         if (this.#loaded && !reload)
             return this.#loaded;
         const a = new Config(definition, projectRoot);
-        const b = await a.loadConfigFile();
+        const b = await a.loadConfigFile(allowGlobal ? argv : undefined);
         this.#loaded = b.parse(argv);
         return this.#loaded;
     }

package/dist/global-bin-dir.d.ts

@@ -0,0 +1,37 @@
+import type { LoadedConfig } from './config/index.ts';
+import type { InstallReceipt } from './install-receipt.ts';
+export type GlobalBinDirSource = 'config' | 'self' | 'local-bin' | 'global-dir';
+export type ResolvedGlobalBinDir = {
+    /** canonical (native realpath) */
+    dir: string;
+    source: GlobalBinDirSource;
+    inPath: boolean;
+    /** self dir passed over because it is not writable */
+    notWritable?: string;
+};
+/** the `vlt` on PATH, when it is the running program */
+export type Self = {
+    /** what `which` found: `<dir>/vlt`, `vlt.cmd`, `vlt.exe` */
+    found: string;
+    /** canonical dirname of `found` */
+    dir: string;
+    /** realpath of what `found` runs */
+    target: string;
+    /** `found` is `process.execPath`: a single executable */
+    standalone: boolean;
+    receipt?: InstallReceipt;
+};
+export type ResolveOptions = {
+    /** skip the self dir, eg after a write there failed */
+    selfUnwritable?: boolean;
+};
+/** `isInPath`, also matching symlinked entries */
+export declare const isInPathRealpath: (dir: string, PATH?: string) => Promise<boolean>;
+/** the `vlt` found in the `PATH`, if it runs this process */
+export declare const findSelf: () => Promise<Self | undefined>;
+/**
+ * Where to link global bins: `--global-bin-dir`, else the dir of the
+ * running `vlt` when writable, else `~/.local/bin` when in the `PATH`
+ * (not win32), else `<global-dir>/bin`.
+ */
+export declare const resolveGlobalBinDir: (conf: Pick<LoadedConfig, "projectRoot" | "globalBinDir">, { selfUnwritable }?: ResolveOptions) => Promise<ResolvedGlobalBinDir>;

package/dist/global-bin-dir.js

@@ -0,0 +1,138 @@
+import { findCmdShimIfExists } from '@vltpkg/cmd-shim';
+import { error } from '@vltpkg/error-cause';
+import { which } from '@vltpkg/which';
+import { constants } from 'node:fs';
+import { access, mkdir, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, delimiter, dirname, isAbsolute, resolve, } from 'node:path';
+import { isInPath } from "./global.js";
+import { globalBinDir, samePath } from "./global-project.js";
+import { readInstallReceipt } from "./install-receipt.js";
+// native realpath: also fixes case on case-insensitive fs
+const real = (p) => realpath(p).catch(() => undefined);
+const writable = (dir) => access(dir, constants.W_OK).then(() => true, () => false);
+/** `isInPath`, also matching symlinked entries */
+export const isInPathRealpath = async (dir, PATH = process.env.PATH ?? '') => {
+    if (isInPath(dir, PATH))
+        return true;
+    const r = await real(dir);
+    if (!r)
+        return false;
+    for (const p of PATH.split(delimiter)) {
+        const rp = p && (await real(p));
+        if (rp && samePath(rp, r))
+            return true;
+    }
+    return false;
+};
+// npx, vlx, run scripts put a project's `.bin` first
+const isDotBin = (d) => {
+    const name = (p) => process.platform === 'win32' ?
+        basename(p).toLowerCase()
+        : basename(p);
+    return name(d) === '.bin' && name(dirname(d)) === 'node_modules';
+};
+/** the `vlt` found in the `PATH`, if it runs this process */
+export const findSelf = async () => {
+    const found = await which('vlt', { nothrow: true }).catch(() => null);
+    if (!found || !isAbsolute(found))
+        return;
+    // win32 looks in the cwd first
+    const foundDir = dirname(found);
+    if (!isInPath(foundDir) || isDotBin(foundDir))
+        return;
+    const dir = await real(foundDir);
+    if (!dir || isDotBin(dir))
+        return;
+    const shim = /\.(cmd|ps1)$/i.test(found) ?
+        (await findCmdShimIfExists(found))?.[1]
+        : found;
+    const target = shim && (await real(shim));
+    if (!target)
+        return;
+    const exec = await real(process.execPath);
+    const standalone = !!exec && samePath(target, exec);
+    if (!standalone) {
+        const script = process.argv[1] && (await real(process.argv[1]));
+        if (!script || !samePath(target, script))
+            return;
+    }
+    const receipt = await readInstallReceipt(found);
+    return {
+        found,
+        dir,
+        target,
+        standalone,
+        ...(receipt ? { receipt } : {}),
+    };
+};
+const resolveDir = async (conf, selfUnwritable) => {
+    const configured = conf.globalBinDir;
+    if (configured) {
+        try {
+            await mkdir(configured, { recursive: true });
+        }
+        catch (cause) {
+            throw error('Could not create global-bin-dir', {
+                code: 'ECONFIG',
+                found: configured,
+                cause,
+            });
+        }
+        try {
+            await access(configured, constants.W_OK);
+        }
+        catch (cause) {
+            throw error('global-bin-dir is not writable', {
+                code: 'ECONFIG',
+                found: configured,
+                cause,
+            });
+        }
+        const dir = await realpath(configured);
+        return {
+            dir,
+            source: 'config',
+            inPath: await isInPathRealpath(dir),
+        };
+    }
+    const self = await findSelf();
+    if (self && !selfUnwritable && (await writable(self.dir))) {
+        return { dir: self.dir, source: 'self', inPath: true };
+    }
+    const notWritable = self?.dir;
+    if (notWritable && process.platform !== 'win32') {
+        // never created: only in the PATH if it existed at login
+        const local = resolve(homedir(), '.local/bin');
+        const st = await stat(local).catch(() => undefined);
+        if (st?.isDirectory() &&
+            (await isInPathRealpath(local)) &&
+            (await writable(local))) {
+            const dir = await realpath(local);
+            // it may be the self dir that refused a write
+            if (!samePath(dir, notWritable)) {
+                return { dir, source: 'local-bin', inPath: true, notWritable };
+            }
+        }
+    }
+    const g = globalBinDir(conf.projectRoot);
+    await mkdir(g, { recursive: true });
+    const dir = await realpath(g);
+    return {
+        dir,
+        source: 'global-dir',
+        inPath: await isInPathRealpath(dir),
+        ...(notWritable ? { notWritable } : {}),
+    };
+};
+/**
+ * Where to link global bins: `--global-bin-dir`, else the dir of the
+ * running `vlt` when writable, else `~/.local/bin` when in the `PATH`
+ * (not win32), else `<global-dir>/bin`.
+ */
+export const resolveGlobalBinDir = async (conf, { selfUnwritable = false } = {}) => {
+    const r = await resolveDir(conf, selfUnwritable);
+    // nested vlt agrees
+    process.env.VLT_GLOBAL_BIN_DIR = r.dir;
+    return r;
+};

package/dist/global-project.d.ts

@@ -0,0 +1,18 @@
+/** commands that support `--global` */
+export declare const globalCommands: ReadonlySet<string>;
+/** folder holding one workspace per global package */
+export declare const globalWorkspacesDir = "packages";
+/** fallback dir for bins of global packages */
+export declare const globalBinDir: (root: string) => string;
+/** same path, case-insensitive on win32 */
+export declare const samePath: (a: string, b: string) => boolean;
+/** path is strictly inside dir */
+export declare const isInside: (dir: string, path: string) => boolean;
+/** throws `EUSAGE` unless an unscoped or `@scope/name` pkg name */
+export declare const assertGlobalName: (name: string) => void;
+/** `eslint` -> `eslint-ws` */
+export declare const globalWorkspaceName: (name: string) => string;
+/** `eslint` -> `packages/eslint-ws`, `@s/p` -> `packages/@s+p-ws` */
+export declare const globalWorkspacePath: (name: string) => string;
+/** create the global project skeleton, keeping existing files */
+export declare const ensureGlobalProject: (root: string) => void;

package/dist/global-project.js

@@ -0,0 +1,67 @@
+import { error } from '@vltpkg/error-cause';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+/** commands that support `--global` */
+export const globalCommands = new Set([
+    'install',
+    'uninstall',
+    'list',
+    'query',
+    'build',
+]);
+/** folder holding one workspace per global package */
+export const globalWorkspacesDir = 'packages';
+/** fallback dir for bins of global packages */
+export const globalBinDir = (root) => resolve(root, 'bin');
+/** same path, case-insensitive on win32 */
+export const samePath = (a, b) => {
+    const norm = (p) => {
+        const r = resolve(p);
+        return process.platform === 'win32' ? r.toLowerCase() : r;
+    };
+    return norm(a) === norm(b);
+};
+/** path is strictly inside dir */
+export const isInside = (dir, path) => {
+    const rel = relative(dir, path);
+    return !!rel && !isAbsolute(rel) && rel.split(sep)[0] !== '..';
+};
+const validName = /^(?:@[a-z0-9][\w.~-]*\/)?[a-z0-9~][\w.~-]*$/i;
+/** throws `EUSAGE` unless an unscoped or `@scope/name` pkg name */
+export const assertGlobalName = (name) => {
+    if (!validName.test(name)) {
+        throw error('Invalid package name', {
+            code: 'EUSAGE',
+            found: name,
+        });
+    }
+};
+/** `eslint` -> `eslint-ws` */
+export const globalWorkspaceName = (name) => {
+    assertGlobalName(name);
+    return `${name}-ws`;
+};
+/** `eslint` -> `packages/eslint-ws`, `@s/p` -> `packages/@s+p-ws` */
+export const globalWorkspacePath = (name) => `${globalWorkspacesDir}/${globalWorkspaceName(name).replace('/', '+')}`;
+const writeIfMissing = (file, data) => {
+    try {
+        writeFileSync(file, JSON.stringify(data, null, 2) + '\n', {
+            flag: 'wx',
+        });
+    }
+    catch (er) {
+        if (er.code !== 'EEXIST')
+            throw er;
+    }
+};
+/** create the global project skeleton, keeping existing files */
+export const ensureGlobalProject = (root) => {
+    mkdirSync(resolve(root, globalWorkspacesDir), { recursive: true });
+    writeIfMissing(resolve(root, 'package.json'), {
+        name: 'vlt-global',
+        private: true,
+    });
+    writeIfMissing(resolve(root, 'vlt.json'), {
+        workspaces: `${globalWorkspacesDir}/*`,
+    });
+};

package/dist/global-state.d.ts

@@ -0,0 +1,24 @@
+/** state of the global project that is not config */
+export type GlobalState = {
+    /** canonical dirs global bins were linked into */
+    binDirs?: string[];
+    /** store dirs of a replaced running vlt, for the next -g command */
+    pendingRemove?: string[];
+    /** the ~/.local/bin notice was shown */
+    localBinNoticed?: boolean;
+    /** 'declined': the install -g PATH offer was answered no */
+    pathSetup?: 'declined';
+    /** keys of other features, kept as-is */
+    [key: string]: unknown;
+};
+export declare const globalStateFile: (root: string) => string;
+/** missing or malformed reads as `{}` */
+export declare const readGlobalState: (root: string) => Promise<GlobalState>;
+/** write `data` via temp file + rename, with `mode` if set */
+export declare const writeFileAtomic: (file: string, data: string | Uint8Array, mode?: number) => Promise<void>;
+/** write `data` as JSON via temp file + rename */
+export declare const writeJsonAtomic: (file: string, data: unknown) => Promise<void>;
+/** read, change and write the state file */
+export declare const updateGlobalState: (root: string, fn: (state: GlobalState) => GlobalState) => Promise<GlobalState>;
+/** rm dirs a running vlt could not remove from under itself */
+export declare const sweepPendingRemove: (root: string) => Promise<void>;

package/dist/global-state.js

@@ -0,0 +1,94 @@
+import { isDepID } from '@vltpkg/dep-id';
+import { isObject } from '@vltpkg/types';
+import { randomBytes } from 'node:crypto';
+import { chmod, readFile, realpath, rename, rm, writeFile, } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, resolve } from 'node:path';
+import { isInside, samePath } from "./global-project.js";
+export const globalStateFile = (root) => resolve(root, 'global-state.json');
+/** missing or malformed reads as `{}` */
+export const readGlobalState = async (root) => {
+    let data;
+    try {
+        data = JSON.parse(await readFile(globalStateFile(root), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+    if (!isObject(data))
+        return {};
+    const state = { ...data };
+    const { binDirs, localBinNoticed } = state;
+    if (Array.isArray(binDirs)) {
+        state.binDirs = binDirs.filter((d) => typeof d === 'string' && isAbsolute(d));
+    }
+    else
+        delete state.binDirs;
+    if (Array.isArray(state.pendingRemove)) {
+        state.pendingRemove = state.pendingRemove.filter((d) => typeof d === 'string' && isAbsolute(d));
+    }
+    else
+        delete state.pendingRemove;
+    if (typeof localBinNoticed !== 'boolean')
+        delete state.localBinNoticed;
+    if (state.pathSetup !== 'declined')
+        delete state.pathSetup;
+    return state;
+};
+/** write `data` via temp file + rename, with `mode` if set */
+export const writeFileAtomic = async (file, data, mode) => {
+    const tmp = `${file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+    try {
+        await writeFile(tmp, data, {
+            flag: 'wx',
+            ...(mode === undefined ? {} : { mode }),
+        });
+        // umask-proof
+        if (mode !== undefined)
+            await chmod(tmp, mode);
+        await rename(tmp, file);
+    }
+    catch (er) {
+        await rm(tmp, { force: true });
+        throw er;
+    }
+};
+/** write `data` as JSON via temp file + rename */
+export const writeJsonAtomic = (file, data) => writeFileAtomic(file, JSON.stringify(data, null, 2) + '\n');
+/** read, change and write the state file */
+export const updateGlobalState = async (root, fn) => {
+    const state = fn(await readGlobalState(root));
+    await writeJsonAtomic(globalStateFile(root), state);
+    return state;
+};
+/** rm dirs a running vlt could not remove from under itself */
+export const sweepPendingRemove = async (root) => {
+    try {
+        const { pendingRemove = [] } = await readGlobalState(root);
+        if (!pendingRemove.length)
+            return;
+        const store = resolve(await realpath(root), 'node_modules/.vlt');
+        const script = process.argv[1];
+        const running = script && (await realpath(script).catch(() => undefined));
+        const left = [];
+        for (const entry of pendingRemove) {
+            // only store dirs, whatever the file says
+            if (!samePath(dirname(entry), store) ||
+                !isDepID(basename(entry))) {
+                continue;
+            }
+            if (running && isInside(entry, running)) {
+                left.push(entry);
+                continue;
+            }
+            // win32: EBUSY while another vlt runs from it
+            await rm(entry, { recursive: true, force: true }).catch(() => left.push(entry));
+        }
+        if (left.length === pendingRemove.length)
+            return;
+        await updateGlobalState(root, s => ({
+            ...s,
+            pendingRemove: left,
+        }));
+    }
+    catch { }
+};