@vltpkg/cli-sdk 1.5.0 → 1.6.1

package/dist/shell-setup/windows.js

@@ -0,0 +1,151 @@
+import { error } from '@vltpkg/error-cause';
+import { promiseSpawn } from '@vltpkg/promise-spawn';
+import { asError } from '@vltpkg/types';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, win32 } from 'node:path';
+export const userEnvKey = 'HKCU\\Environment';
+/** how the user Path is named in messages */
+export const userEnvLabel = 'your Windows user environment';
+/** where users edit their Path by hand */
+export const editPathHint = 'Start > "Edit environment variables for your account" > Path';
+const refreshVar = 'VLT_PATH_REFRESH';
+const system32 = (env) => win32.join([env.SystemRoot, env.windir].find(d => d && win32.isAbsolute(d)) ?? 'C:\\Windows', 'System32');
+// absolute: never a reg.exe from the cwd
+const run = (env, exe, args) => promiseSpawn(win32.join(system32(env), exe), args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+});
+// reg's stderr, else the spawn error
+const detail = (er) => {
+    const e = asError(er);
+    const c = e.cause;
+    return (typeof c?.stderr === 'string' && c.stderr ? c.stderr
+        : c?.cause ? asError(c.cause).message
+            : e.message);
+};
+const fail = (what, key, why, hint, cause) => error(`Could not ${what} your user Path (${key}): ${why}\n  ${hint}`, {
+    code: 'ECONFIG',
+    cause,
+});
+const addIt = (dir) => `Add ${dir} yourself: ${editPathHint}`;
+const norm = (p, env) => win32
+    .normalize(expandEnv(p.trim().replace(/^"(.*)"$/, '$1'), env))
+    .replace(/[\\/]+$/, '')
+    .toLowerCase();
+// .reg strings escape \ and "
+const unesc = (s) => s.replace(/\\([\s\S])/g, '$1');
+/** `name` in the first key of a `reg export` file */
+export const parseRegExport = (text, name) => {
+    // hex values wrap as `,\` + newline + indent
+    const lines = text.replace(/,\\\r?\n */g, ',').split(/\r?\n/);
+    let inKey = false;
+    for (const line of lines) {
+        if (line.startsWith('[')) {
+            // subkeys follow
+            if (inKey)
+                return undefined;
+            inKey = true;
+            continue;
+        }
+        // [\s\S]: data may hold \r, U+2028, U+2029
+        const [, n = '', v = ''] = /^"((?:[^"\\]|\\[\s\S])*)"=([\s\S]*)$/.exec(line) ?? [];
+        if (!inKey || unesc(n).toLowerCase() !== name.toLowerCase()) {
+            continue;
+        }
+        const [, sz] = /^"((?:[^"\\]|\\[\s\S])*)"$/.exec(v) ?? [];
+        if (sz !== undefined)
+            return { type: 'REG_SZ', data: unesc(sz) };
+        const [, hex] = /^hex\(2\):([\da-f,]*)$/i.exec(v) ?? [];
+        if (hex !== undefined) {
+            const bytes = hex
+                .split(',')
+                .filter(Boolean)
+                .map(h => parseInt(h, 16));
+            return {
+                type: 'REG_EXPAND_SZ',
+                data: Buffer.from(bytes)
+                    .toString('utf16le')
+                    .replace(/\0+$/, ''),
+            };
+        }
+        return { type: v.replace(/:[\s\S]*$/, ''), data: '' };
+    }
+    return undefined;
+};
+/** `%VAR%` expanded, names case-insensitive */
+export const expandEnv = (s, env = process.env) => s.replace(/%([^%]+)%/g, (m, n) => Object.entries(env).find(([k]) => k.toLowerCase() === n.toLowerCase())?.[1] ?? m);
+/** Path with `dir` first, unless already in it */
+export const addPathEntry = (value, dir, env = process.env) => {
+    if (!value)
+        return { action: 'create', data: dir };
+    const previous = value.data;
+    const d = norm(dir, env);
+    if (previous.split(';').some(e => e.trim() && norm(e, env) === d)) {
+        return { action: 'unchanged', previous, data: previous };
+    }
+    return {
+        action: 'prepend',
+        previous,
+        data: previous ? `${dir};${previous}` : dir,
+    };
+};
+/** the user Path value, undefined when not set */
+export const readUserPath = async ({ env = process.env, key = userEnvKey, } = {}) => {
+    const d = await mkdtemp(join(tmpdir(), 'vlt-'));
+    const file = join(d, 'env.reg');
+    try {
+        // utf-16 file: reg query prints in the console code page
+        await run(env, 'reg.exe', ['export', key, file, '/y']);
+        const v = parseRegExport((await readFile(file)).toString('utf16le'), 'Path');
+        // lone surrogate or NUL: would not survive the write
+        if (v && /[\p{Cs}\0]/u.test(v.data)) {
+            throw new Error('it has characters vlt could not read');
+        }
+        return v;
+    }
+    finally {
+        // AV may hold the new file
+        await rm(d, {
+            recursive: true,
+            force: true,
+            maxRetries: 3,
+        }).catch(() => { });
+    }
+};
+/** what adding `dir` to the user Path would change */
+export const planWindowsPath = async (dir, { env = process.env, key = userEnvKey } = {}) => {
+    // would split or expand in Path
+    if (/[;%]/.test(dir)) {
+        throw fail('update', key, `the folder name has ";" or "%"`, 'Set --global-bin-dir to a folder without them');
+    }
+    const value = await readUserPath({ env, key }).catch((er) => {
+        throw fail('read', key, detail(er), addIt(dir), er);
+    });
+    if (value && !/^REG_(EXPAND_)?SZ$/.test(value.type)) {
+        throw fail('update', key, `unexpected value type ${value.type}`, addIt(dir));
+    }
+    return { key, dir, ...addPathEntry(value, dir, env) };
+};
+/** write the planned Path, then tell running programs */
+export const applyWindowsPath = async (c, { env = process.env } = {}) => {
+    await run(env, 'reg.exe', [
+        'add',
+        c.key,
+        '/v',
+        'Path',
+        '/t',
+        'REG_EXPAND_SZ',
+        '/d',
+        c.data,
+        '/f',
+    ]).catch((er) => {
+        throw fail('update', c.key, detail(er), addIt(c.dir), er);
+    });
+    if (c.key !== userEnvKey)
+        return;
+    // setx broadcasts WM_SETTINGCHANGE: new terminals see the new Path
+    await run(env, 'setx.exe', [refreshVar, '1'])
+        .then(() => run(env, 'reg.exe', ['delete', c.key, '/v', refreshVar, '/f']))
+        .catch(() => { });
+};

package/dist/shell.d.ts

@@ -0,0 +1,18 @@
+export type Shell = 'bash' | 'zsh' | 'fish' | 'sh' | 'nu' | 'pwsh' | 'cmd' | 'unknown';
+export type ShellOptions = {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    home?: string;
+};
+/** `~/x` for a path under the home dir */
+export declare const prettyPath: (path: string, home?: string, win32?: boolean) => string;
+/** the user's shell, from `SHELL`, or a guess on win32 */
+export declare const detectShell: (env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform) => Shell;
+/** `dir` double-quoted for a POSIX shell, `$HOME` late-bound */
+export declare const posixPath: (dir: string, o?: ShellOptions) => string;
+/** `dir` double-quoted for fish, `$HOME` late-bound */
+export declare const fishPath: (dir: string, o?: ShellOptions) => string;
+/** the line that adds `dir` to the `PATH` in `shell` */
+export declare const shellPathCommand: (shell: Shell, dir: string, o?: ShellOptions) => string;
+/** rc file to add the `PATH` line to, for display */
+export declare const shellRcFile: (shell: Shell, o?: ShellOptions) => string | undefined;

package/dist/shell.js

@@ -0,0 +1,110 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+const shells = new Map([
+    ['bash', 'bash'],
+    ['zsh', 'zsh'],
+    ['fish', 'fish'],
+    ['nu', 'nu'],
+    ['pwsh', 'pwsh'],
+    ['powershell', 'pwsh'],
+    ['sh', 'sh'],
+    ['dash', 'sh'],
+    ['ksh', 'sh'],
+    ['mksh', 'sh'],
+    ['ash', 'sh'],
+]);
+const isSep = (c, win32) => c === '/' || (win32 && c === '\\');
+// rest of `path` after `home`: '' for home itself, undefined outside
+const homeRest = (path, home, win32) => !home ? undefined
+    : path === home ? ''
+        : path.startsWith(home) && isSep(path[home.length], win32) ?
+            path.slice(home.length)
+            : undefined;
+/** `~/x` for a path under the home dir */
+export const prettyPath = (path, home = homedir(), win32 = process.platform === 'win32') => {
+    const rest = homeRest(path, home, win32);
+    return rest === undefined ? path : `~${rest}`;
+};
+/** the user's shell, from `SHELL`, or a guess on win32 */
+export const detectShell = (env = process.env, platform = process.platform) => {
+    const { SHELL } = env;
+    if (SHELL) {
+        const name = SHELL.replace(/^.*[\\/]/, '')
+            .replace(/\.exe$/i, '')
+            .toLowerCase();
+        return shells.get(name) ?? 'unknown';
+    }
+    if (platform !== 'win32')
+        return 'unknown';
+    // set machine-wide, PowerShell adds the user module dir
+    const mods = (env.PSModulePath ?? '').split(';').filter(Boolean);
+    return mods.length >= 3 ? 'pwsh' : 'cmd';
+};
+const opts = ({ env = process.env, platform = process.platform, home = homedir(), }) => ({
+    env,
+    platform,
+    home,
+    win32: platform === 'win32',
+});
+const escape = (s, chars, esc = '\\') => s.replace(chars, c => esc + c);
+// `$HOME/x`, or the path, `/c/x` style on win32
+const posixInner = (dir, o, chars) => {
+    const { home, win32 } = opts(o);
+    const slash = (p) => (win32 ? p.replace(/\\/g, '/') : p);
+    const rest = homeRest(dir, home, win32);
+    if (rest !== undefined)
+        return '$HOME' + escape(slash(rest), chars);
+    const p = win32 ?
+        slash(dir).replace(/^([a-z]):/i, (_, d) => `/${d.toLowerCase()}`)
+        : dir;
+    return escape(p, chars);
+};
+const shChars = /[\\"$`]/g;
+/** `dir` double-quoted for a POSIX shell, `$HOME` late-bound */
+export const posixPath = (dir, o = {}) => `"${posixInner(dir, o, shChars)}"`;
+/** `dir` double-quoted for fish, `$HOME` late-bound */
+export const fishPath = (dir, o = {}) => `"${posixInner(dir, o, /[\\"$]/g)}"`;
+/** the line that adds `dir` to the `PATH` in `shell` */
+export const shellPathCommand = (shell, dir, o = {}) => {
+    const { home, win32 } = opts(o);
+    const rest = homeRest(dir, home, win32);
+    switch (shell) {
+        case 'fish':
+            return `fish_add_path ${fishPath(dir, o)}`;
+        case 'nu':
+            return `$env.PATH = ($env.PATH | prepend "${escape(dir, /[\\"]/g)}")`;
+        case 'pwsh': {
+            const p = rest === undefined ?
+                escape(dir, /[`"$]/g, '`')
+                : '$HOME' + escape(rest, /[`"$]/g, '`');
+            return `$env:PATH += "${win32 ? ';' : ':'}${p}"`;
+        }
+        case 'cmd':
+            return `set "PATH=%PATH%;${rest === undefined ? dir : '%USERPROFILE%' + rest}"`;
+        default:
+            return `export PATH="${posixInner(dir, o, shChars)}:$PATH"`;
+    }
+};
+/** rc file to add the `PATH` line to, for display */
+export const shellRcFile = (shell, o = {}) => {
+    const { env, platform, home, win32 } = opts(o);
+    switch (shell) {
+        case 'zsh':
+            return prettyPath(`${env.ZDOTDIR || home}/.zshrc`, home, win32);
+        case 'bash': {
+            const has = (f) => existsSync(`${home}/${f}`);
+            // like `vlt setup --path`: never a new .bashrc
+            if (platform !== 'darwin' && has('.bashrc'))
+                return '~/.bashrc';
+            // a new .bash_profile would shadow .profile
+            const f = ['.bash_profile', '.bash_login'].find(has);
+            return `~/${f ?? '.profile'}`;
+        }
+        case 'sh':
+            return env.ENV ? prettyPath(env.ENV, home, win32) : '~/.profile';
+        case 'pwsh':
+            return '$PROFILE';
+        default:
+            return undefined;
+    }
+};

package/dist/telemetry.js

@@ -73,9 +73,16 @@ const getClient = () => {
             // call shutdown at the end so this is just a safety net.
             flushAt: 20,
             flushInterval: 10_000,
+            // one attempt, capped like flush(); failed sends resolve as 204
+            // so offline or erroring runs neither wait nor log
+            fetchRetryCount: 0,
+            requestTimeout: SHUTDOWN_TIMEOUT_MS,
+            fetch: async (url, init) => {
+                const res = await fetch(url, init).catch(() => undefined);
+                return res?.ok ? res : new Response(null, { status: 204 });
+            },
         });
         return _posthog;
-        /* c8 ignore next 4 */
     }
     catch {
         _initFailed = true;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/cli-sdk",
   "description": "The source for the vlt CLI",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -14,33 +14,35 @@
   },
   "dependencies": {
     "@resvg/resvg-wasm": "^2.6.2",
-    "@vltpkg/config": "1.5.0",
-    "@vltpkg/dep-id": "1.5.0",
-    "@vltpkg/dot-prop": "1.5.0",
-    "@vltpkg/error-cause": "1.5.0",
-    "@vltpkg/git": "1.5.0",
-    "@vltpkg/graph": "1.5.0",
-    "@vltpkg/graph-run": "1.5.0",
-    "@vltpkg/init": "1.5.0",
-    "@vltpkg/output": "1.5.0",
-    "@vltpkg/package-info": "1.5.0",
-    "@vltpkg/package-json": "1.5.0",
-    "@vltpkg/pick-manifest": "1.5.0",
-    "@vltpkg/promise-spawn": "1.5.0",
-    "@vltpkg/query": "1.5.0",
-    "@vltpkg/registry-client": "1.5.0",
-    "@vltpkg/rollback-remove": "1.5.0",
-    "@vltpkg/run": "1.5.0",
-    "@vltpkg/security-archive": "1.5.0",
-    "@vltpkg/semver": "1.5.0",
-    "@vltpkg/spec": "1.5.0",
-    "@vltpkg/tar": "1.5.0",
-    "@vltpkg/types": "1.5.0",
-    "@vltpkg/url-open": "1.5.0",
-    "@vltpkg/vlt-json": "1.5.0",
-    "@vltpkg/vlx": "1.5.0",
-    "@vltpkg/workspaces": "1.5.0",
-    "@vltpkg/xdg": "1.5.0",
+    "@vltpkg/cmd-shim": "1.6.1",
+    "@vltpkg/config": "1.6.1",
+    "@vltpkg/dep-id": "1.6.1",
+    "@vltpkg/dot-prop": "1.6.1",
+    "@vltpkg/error-cause": "1.6.1",
+    "@vltpkg/git": "1.6.1",
+    "@vltpkg/graph": "1.6.1",
+    "@vltpkg/graph-run": "1.6.1",
+    "@vltpkg/init": "1.6.1",
+    "@vltpkg/output": "1.6.1",
+    "@vltpkg/package-info": "1.6.1",
+    "@vltpkg/package-json": "1.6.1",
+    "@vltpkg/pick-manifest": "1.6.1",
+    "@vltpkg/promise-spawn": "1.6.1",
+    "@vltpkg/query": "1.6.1",
+    "@vltpkg/registry-client": "1.6.1",
+    "@vltpkg/rollback-remove": "1.6.1",
+    "@vltpkg/run": "1.6.1",
+    "@vltpkg/security-archive": "1.6.1",
+    "@vltpkg/semver": "1.6.1",
+    "@vltpkg/spec": "1.6.1",
+    "@vltpkg/tar": "1.6.1",
+    "@vltpkg/types": "1.6.1",
+    "@vltpkg/url-open": "1.6.1",
+    "@vltpkg/vlt-json": "1.6.1",
+    "@vltpkg/vlx": "1.6.1",
+    "@vltpkg/which": "1.6.1",
+    "@vltpkg/workspaces": "1.6.1",
+    "@vltpkg/xdg": "1.6.1",
     "ansi-to-pre": "^1.0.6",
     "beautiful-mermaid": "^1.1.3",
     "chalk": "^5.6.2",