@vltpkg/run 1.0.0-rc.23 → 1.0.0-rc.25

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+import { PackageJson } from '@vltpkg/package-json';
+import type { PromiseSpawnOptions, SpawnResultNoStdio, SpawnResultStdioStrings } from '@vltpkg/promise-spawn';
+import type { Manifest } from '@vltpkg/types';
+export * from './node-gyp.ts';
+/** options shared by run() and exec() */
+export type SharedOptions = PromiseSpawnOptions & {
+    /** additional arguments to pass to the command */
+    args?: string[];
+    /** the root of the project, which we don't walk up past */
+    projectRoot: string;
+    /** the directory where the package.json lives and the script runs */
+    cwd: string;
+    /**
+     * environment variables to set. `process.env` is always included,
+     * to omit fields, set them explicitly to undefined.
+     *
+     * vlt will add some of its own, as well:
+     * - npm_lifecycle_event: the event name
+     * - npm_lifecycle_script: the command in package.json#scripts
+     * - npm_package_json: path to the package.json file
+     * - VLT_* envs for all vlt configuration values that are set
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * the shell to run the script in. If not set, then the default
+     * platform-specific shell will be used.
+     */
+    'script-shell'?: boolean | string;
+    /**
+     * If true, then `FORCE_COLOR=1` will be set in the environment so that
+     * scripts will typically have colored output enablled, even if the output
+     * is not a tty.
+     */
+    color?: boolean;
+};
+/**
+ * Options for run() and runFG()
+ */
+export type RunOptions = SharedOptions & {
+    /** the name of the thing in package.json#scripts */
+    arg0: string;
+    /**
+     * pass in a @vltpkg/package-json.PackageJson instance, and
+     * it'll be used for reading the package.json file. Optional,
+     * may improve performance somewhat.
+     */
+    packageJson?: PackageJson;
+    /**
+     * Pass in a manifest to avoid having to read it at all
+     */
+    manifest?: Pick<Manifest, 'scripts' | 'gypfile'>;
+    /**
+     * if the script is not defined in package.json#scripts, just ignore it and
+     * treat as success. Otherwise, treat as an error. Default false.
+     */
+    ignoreMissing?: boolean;
+    /**
+     * skip the pre/post commands, just run the one specified.
+     * This can be used to run JUST the specified script, without any
+     * pre/post commands.
+     */
+    ignorePrePost?: boolean;
+};
+/**
+ * Options for exec() and execFG()
+ */
+export type ExecOptions = SharedOptions & {
+    /** the command to execute */
+    arg0: string;
+};
+/**
+ * Options for runExec() and runExecFG()
+ */
+export type RunExecOptions = SharedOptions & {
+    /**
+     * Either the command to be executed, or the event to be run
+     */
+    arg0: string;
+    /**
+     * pass in a @vltpkg/package-json.PackageJson instance, and
+     * it'll be used for reading the package.json file. Optional,
+     * may improve performance somewhat.
+     */
+    packageJson?: PackageJson;
+};
+/**
+ * Run a package.json#scripts event in the background
+ */
+export declare const run: (options: RunOptions) => Promise<RunResult>;
+/**
+ * Run a package.json#scripts event in the foreground
+ */
+export declare const runFG: (options: RunOptions) => Promise<RunFGResult>;
+/** Return type of {@link run} */
+export type RunResult = SpawnResultStdioStrings & {
+    pre?: SpawnResultStdioStrings;
+    post?: SpawnResultStdioStrings;
+};
+/** Return type of {@link runFG} */
+export type RunFGResult = SpawnResultNoStdio & {
+    pre?: SpawnResultNoStdio;
+    post?: SpawnResultNoStdio;
+};
+export declare const isRunResult: (v: unknown) => v is RunResult;
+/**
+ * Return type of {@link run} or {@link runFG}, as determined by their base
+ * type
+ * @internal
+ */
+export type RunImplResult<R extends SpawnResultNoStdio | SpawnResultStdioStrings> = R & {
+    pre?: R;
+    post?: R;
+};
+/**
+ * Execute an arbitrary command in the background
+ */
+export declare const exec: (options: ExecOptions) => Promise<SpawnResultStdioStrings>;
+/**
+ * Execute an arbitrary command in the foreground
+ */
+export declare const execFG: (options: ExecOptions) => Promise<SpawnResultNoStdio>;
+/**
+ * If the arg0 is a defined package.json script, then run(), otherwise exec()
+ */
+export declare const runExec: (options: RunExecOptions) => Promise<RunResult | SpawnResultStdioStrings>;
+/**
+ * If the arg0 is a defined package.json script, then runFG(), otherwise
+ * execFG()
+ */
+export declare const runExecFG: (options: RunExecOptions) => Promise<RunFGResult | SpawnResultNoStdio>;

package/dist/index.js

@@ -0,0 +1,287 @@
+import { error } from '@vltpkg/error-cause';
+import { PackageJson } from '@vltpkg/package-json';
+import { promiseSpawn } from '@vltpkg/promise-spawn';
+import { foregroundChild } from 'foreground-child';
+import { proxySignals } from 'foreground-child/proxy-signals';
+import { statSync } from 'node:fs';
+import { delimiter, resolve, sep } from 'node:path';
+import { walkUp } from 'walk-up-path';
+import { getNodeGypShimDir, hasNodeGypReference, hasNodeGypBinding, } from "./node-gyp.js";
+// Re-export all named exports from node-gyp.ts
+export * from "./node-gyp.js";
+/** map of which node_modules/.bin folders exist */
+const dotBins = new Map();
+/** Check if a directory exists, and cache result */
+const dirExists = (p) => {
+    const cached = dotBins.get(p);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const isDir = statSync(p).isDirectory();
+        dotBins.set(p, isDir);
+        return isDir;
+    }
+    catch {
+        dotBins.set(p, false);
+        return false;
+    }
+};
+const nmBin = `${sep}node_modules${sep}.bin`;
+/**
+ * Add all existing `node_modules/.bin` folders to the PATH that
+ * exist between the cwd and the projectRoot, so dependency bins
+ * are found, with closer paths higher priority.
+ *
+ * If command contains node-gyp reference, also inject the shim directory
+ * as a fallback (after all existing PATH entries).
+ */
+const addPaths = async (projectRoot, cwd, env, command) => {
+    const { PATH = '' } = env;
+    const PATHsplit = PATH.split(delimiter);
+    const paths = new Set();
+    // anything in the PATH that already has node_modules/.bin is a thing
+    // we put there, perhaps for the vlx exec cache usage
+    for (const p of PATHsplit) {
+        if (p.endsWith(nmBin)) {
+            paths.add(p);
+        }
+    }
+    for (const p of walkUp(cwd)) {
+        const dotBin = resolve(p, 'node_modules/.bin');
+        if (dirExists(dotBin))
+            paths.add(dotBin);
+        if (p === projectRoot)
+            break;
+    }
+    for (const p of PATH.split(delimiter)) {
+        /* c8 ignore next - pretty rare to have an empty entry */
+        if (p)
+            paths.add(p);
+    }
+    // If command has node-gyp, inject shim directory as fallback (last)
+    if (command && hasNodeGypReference(command)) {
+        try {
+            const shimDir = await getNodeGypShimDir();
+            paths.add(shimDir);
+            /* c8 ignore start */
+        }
+        catch {
+            // Ignore shim creation errors, command will fail naturally if node-gyp is needed
+        }
+        /* c8 ignore stop */
+    }
+    env.PATH = [...paths].join(delimiter);
+    return env;
+};
+/**
+ * Run a package.json#scripts event in the background
+ */
+export const run = async (options) => runImpl(options, exec, '');
+/**
+ * Run a package.json#scripts event in the foreground
+ */
+export const runFG = async (options) => runImpl(options, execFG, null);
+export const isRunResult = (v) => !!v &&
+    typeof v === 'object' &&
+    !Array.isArray(v) &&
+    'stdout' in v &&
+    'stderr' in v &&
+    'status' in v &&
+    'signal' in v;
+/**
+ * Internal implementation of run() and runFG(), since they're mostly identical
+ */
+const runImpl = async (options, execImpl, empty) => {
+    const { arg0, packageJson = new PackageJson(), ignoreMissing = false, manifest, 'script-shell': shell = true, ...execArgs } = options;
+    const pjPath = resolve(options.cwd, 'package.json');
+    // npm adds a `"install": "node-gyp rebuild"` if a binding.gyp
+    // is present at the time of publish, EVEN IF it's not included
+    // in the package. So, we need to read the actual package.json
+    // in those cases.
+    const untrustworthy = !!(manifest?.gypfile &&
+        arg0 === 'install' &&
+        manifest.scripts?.install === 'node-gyp rebuild');
+    const pj = (untrustworthy ? undefined : manifest) ??
+        packageJson.read(options.cwd);
+    const { scripts } = pj;
+    const command = scripts?.[arg0] ??
+        // npm's implicit install behavior: "If there is a binding.gyp file in the
+        // root of your package and you haven't defined your own install or preinstall
+        // scripts, npm will default the install command to compile using node-gyp
+        // via node-gyp rebuild"
+        ((arg0 === 'install' &&
+            !scripts?.install &&
+            !scripts?.preinstall &&
+            hasNodeGypBinding(options.cwd)) ?
+            'node-gyp rebuild'
+            : undefined);
+    // Check for pre/post commands even if main command doesn't exist for cases
+    // like packages that have only a preinstall or postinstall script.
+    const precommand = !options.ignorePrePost && scripts?.[`pre${arg0}`];
+    const postcommand = !options.ignorePrePost && scripts?.[`post${arg0}`];
+    const emptyResult = () => ({
+        command: '',
+        args: execArgs.args ?? [],
+        cwd: options.cwd,
+        status: 0,
+        signal: null,
+        stdout: empty,
+        stderr: empty,
+    });
+    const execCommand = (command, preOrPost) => execImpl({
+        arg0: command,
+        ...execArgs,
+        'script-shell': shell,
+        // pre/post scripts always have empty args, main script uses execArgs.args
+        args: preOrPost ? [] : (execArgs.args ?? []),
+        env: {
+            ...execArgs.env,
+            npm_package_json: pjPath,
+            npm_lifecycle_event: `${preOrPost ?? ''}${arg0}`,
+            npm_lifecycle_script: command,
+        },
+    });
+    if (!command && !precommand && !postcommand) {
+        if (ignoreMissing) {
+            return emptyResult();
+        }
+        throw error('Script not defined in package.json', {
+            name: arg0,
+            cwd: options.cwd,
+            args: options.args,
+            path: pjPath,
+            manifest: pj,
+        });
+    }
+    const pre = precommand ? await execCommand(precommand, 'pre') : undefined;
+    if (pre?.status || pre?.signal) {
+        return {
+            ...pre,
+        };
+    }
+    const main = command ? await execCommand(command) : emptyResult();
+    if (main.signal || main.status) {
+        return {
+            ...main,
+            ...(pre ? { pre } : {}),
+        };
+    }
+    const post = postcommand ? await execCommand(postcommand, 'post') : undefined;
+    if (post?.signal || post?.status) {
+        return {
+            ...main,
+            ...(pre ? { pre } : {}),
+            post,
+            signal: post.signal,
+            status: post.status,
+        };
+    }
+    return {
+        ...main,
+        ...(pre ? { pre } : {}),
+        ...(post ? { post } : {}),
+    };
+};
+/**
+ * Escapes a string for safe inclusion in a POSIX shell command.
+ * Wraps in single quotes and escapes any embedded single quotes.
+ */
+const shellEscape = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+const isPosixShell = (shell) => {
+    if (typeof shell === 'string')
+        return !/(^|\\)cmd\.exe$/i.test(shell);
+    return process.platform !== 'win32';
+};
+/**
+ * When running through a POSIX shell, Node.js joins `spawn(cmd, args)`
+ * into a single string without escaping (DEP0190). This means
+ * characters like `#` are interpreted as shell comments, silently
+ * swallowing the rest of the command line.
+ *
+ * Fix: append shell-escaped args directly to the command string
+ * so the script is still shell-interpreted but args are passed
+ * literally.
+ *
+ * On Windows with cmd.exe, these characters are not special, so
+ * we leave args as-is to avoid injecting POSIX quotes that cmd.exe
+ * would pass through literally.
+ */
+const withShellArgs = (shell, arg0, args) => {
+    if (!shell || args.length === 0 || !isPosixShell(shell))
+        return [arg0, args];
+    return [`${arg0} ${args.map(shellEscape).join(' ')}`, []];
+};
+/**
+ * Execute an arbitrary command in the background
+ */
+export const exec = async (options) => {
+    const { arg0, args = [], cwd, env = {}, projectRoot, 'script-shell': shell = false, color = false, signal, ...spawnOptions } = options;
+    const [spawnCmd, spawnArgs] = withShellArgs(shell, arg0, args);
+    const p = promiseSpawn(spawnCmd, spawnArgs, {
+        ...spawnOptions,
+        shell,
+        stdio: 'pipe',
+        stdioString: true,
+        cwd,
+        env: await addPaths(projectRoot, cwd, {
+            ...process.env,
+            ...env,
+            FORCE_COLOR: color ? '1' : '0',
+        }, arg0),
+        windowsHide: true,
+    });
+    proxySignals(p.process);
+    return await p;
+};
+/**
+ * Execute an arbitrary command in the foreground
+ */
+export const execFG = async (options) => {
+    const { arg0, args = [], cwd, projectRoot, env = {}, 'script-shell': shell = false, color = true, signal, ...spawnOptions } = options;
+    const [spawnCmd, spawnArgs] = withShellArgs(shell, arg0, args);
+    const processEnv = await addPaths(projectRoot, cwd, {
+        ...process.env,
+        ...env,
+        FORCE_COLOR: color ? '1' : '0',
+    }, arg0);
+    return new Promise(res => {
+        foregroundChild(spawnCmd, spawnArgs, {
+            ...spawnOptions,
+            shell,
+            cwd,
+            env: processEnv,
+        }, (status, signal) => {
+            res({
+                command: arg0,
+                args,
+                cwd,
+                stdout: null,
+                stderr: null,
+                status,
+                signal,
+            });
+            return false;
+        });
+    });
+};
+const runExecImpl = async (options, runImpl, execImpl) => {
+    const { arg0, packageJson = new PackageJson(), ...args } = options;
+    const pj = packageJson.read(options.cwd);
+    const { scripts } = pj;
+    const command = scripts?.[arg0];
+    if (command) {
+        return runImpl({ ...args, packageJson, arg0 });
+    }
+    else {
+        return execImpl({ ...args, arg0 });
+    }
+};
+/**
+ * If the arg0 is a defined package.json script, then run(), otherwise exec()
+ */
+export const runExec = async (options) => runExecImpl(options, run, exec);
+/**
+ * If the arg0 is a defined package.json script, then runFG(), otherwise
+ * execFG()
+ */
+export const runExecFG = async (options) => runExecImpl(options, runFG, execFG);

package/dist/node-gyp.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Get or create the node-gyp shim file path
+ * The shim redirects node-gyp calls to vlx node-gyp@latest
+ */
+export declare function getNodeGypShim(): Promise<string>;
+/**
+ * Get the directory containing the node-gyp shim
+ * This can be prepended to PATH to make the shim available
+ */
+export declare function getNodeGypShimDir(): Promise<string>;
+/**
+ * Check if a command contains node-gyp references
+ */
+export declare function hasNodeGypReference(command: string): boolean;
+/**
+ * Check if a binding.gyp file exists
+ */
+export declare function hasNodeGypBinding(cwd: string): boolean;

package/dist/node-gyp.js

@@ -0,0 +1,68 @@
+import { XDG } from '@vltpkg/xdg';
+import { statSync } from 'node:fs';
+import { chmod, mkdir, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+const xdg = new XDG('vlt');
+let shimPath;
+/**
+ * Get or create the node-gyp shim file path
+ * The shim redirects node-gyp calls to vlx node-gyp@latest
+ */
+export async function getNodeGypShim() {
+    if (shimPath)
+        return shimPath;
+    const runtimeDir = xdg.runtime('run');
+    const shimFile = join(runtimeDir, 'node-gyp');
+    // Check if shim already exists
+    try {
+        await stat(shimFile);
+        /* c8 ignore next 2 - hard to test */
+        shimPath = shimFile;
+        return shimPath;
+    }
+    catch {
+        // Shim doesn't exist, create it
+    }
+    // Create runtime directory if needed
+    await mkdir(runtimeDir, { recursive: true });
+    // Create shim that calls vlx
+    /* c8 ignore start - ignore platform-dependent coverage */
+    const shimContent = process.platform === 'win32' ?
+        `@echo off\nvlx --yes node-gyp@latest %*\n`
+        : `#!/bin/sh\nexec vlx --yes node-gyp@latest "$@"\n`;
+    /* c8 ignore stop */
+    await writeFile(shimFile, shimContent, 'utf8');
+    // Make executable on Unix systems
+    /* c8 ignore start - unix-only */
+    if (process.platform !== 'win32') {
+        await chmod(shimFile, 0o755);
+    }
+    /* c8 ignore stop */
+    shimPath = shimFile;
+    return shimPath;
+}
+/**
+ * Get the directory containing the node-gyp shim
+ * This can be prepended to PATH to make the shim available
+ */
+export async function getNodeGypShimDir() {
+    const shim = await getNodeGypShim();
+    return dirname(shim);
+}
+/**
+ * Check if a command contains node-gyp references
+ */
+export function hasNodeGypReference(command) {
+    return command.includes('node-gyp');
+}
+/**
+ * Check if a binding.gyp file exists
+ */
+export function hasNodeGypBinding(cwd) {
+    try {
+        return statSync(join(cwd, 'binding.gyp')).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/run",
   "description": "Run package.json scripts and execute commands",
-  "version": "1.0.0-rc.23",
+  "version": "1.0.0-rc.25",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -12,11 +12,11 @@
     "email": "support@vlt.sh"
   },
   "dependencies": {
-    "@vltpkg/error-cause": "1.0.0-rc.23",
-    "@vltpkg/package-json": "1.0.0-rc.23",
-    "@vltpkg/promise-spawn": "1.0.0-rc.23",
-    "@vltpkg/types": "1.0.0-rc.23",
-    "@vltpkg/xdg": "1.0.0-rc.23",
+    "@vltpkg/error-cause": "1.0.0-rc.25",
+    "@vltpkg/package-json": "1.0.0-rc.25",
+    "@vltpkg/promise-spawn": "1.0.0-rc.25",
+    "@vltpkg/types": "1.0.0-rc.25",
+    "@vltpkg/xdg": "1.0.0-rc.25",
     "foreground-child": "^3.3.1",
     "walk-up-path": "^4.0.0"
   },