@vltpkg/cli-sdk 1.0.0-rc.23 → 1.0.0-rc.24

package/dist/commands/docs.js

@@ -0,0 +1,153 @@
+import { error } from '@vltpkg/error-cause';
+import { PackageInfoClient } from '@vltpkg/package-info';
+import { Spec } from '@vltpkg/spec';
+import { urlOpen } from '@vltpkg/url-open';
+import { actual } from '@vltpkg/graph';
+import { Query } from '@vltpkg/query';
+import { SecurityArchive } from '@vltpkg/security-archive';
+import { createHostContextsMap } from "../query-host-contexts.js";
+import { commandUsage } from "../config/usage.js";
+import hostedGitInfo from 'hosted-git-info';
+const { fromUrl: hostedGitInfoFromUrl } = hostedGitInfo;
+export const usage = () => commandUsage({
+    command: 'docs',
+    usage: ['[<spec>]', '[--target=<query>]'],
+    description: `Open documentation for a package in a web browser.
+                  Reads repository information from package.json or fetches
+                  manifest data for the specified package.`,
+    options: {
+        target: {
+            value: '<query>',
+            description: 'Query selector to filter packages using DSS syntax.',
+        },
+    },
+    examples: {
+        '': {
+            description: 'Open docs for the current package (reads local package.json)',
+        },
+        'abbrev@2.0.0': {
+            description: 'Open docs for a specific package version',
+        },
+        '--target=":root > *"': {
+            description: 'List documentation URLs for all direct dependencies',
+        },
+    },
+});
+export const views = {
+    human: r => {
+        if (Array.isArray(r)) {
+            let msg = 'Multiple package docs found:\n';
+            msg += r.map(item => `• ${item.name}: ${item.url}`).join('\n');
+            return msg;
+        }
+        return '';
+    },
+    json: r => r,
+};
+const getUrlFromManifest = (manifest) => {
+    const { name, homepage, repository } = manifest;
+    if (!name) {
+        throw error('No package name found');
+    }
+    // Extract repository URL
+    let url;
+    if (homepage) {
+        url = homepage;
+    }
+    else if (repository) {
+        const repoUrl = typeof repository === 'string' ? repository
+            : typeof repository === 'object' && 'url' in repository ?
+                repository.url
+                : /* c8 ignore next */ undefined;
+        if (repoUrl) {
+            // Try to get hosted git info
+            const info = hostedGitInfoFromUrl(repoUrl.replace(/^git\+/, ''));
+            if (info?.docs && typeof info.docs === 'function') {
+                url = info.docs();
+            }
+        }
+    }
+    // Fallback to vlt.io package page
+    if (!url) {
+        url = `https://vlt.io/explore/npm/${name}/overview`;
+    }
+    return url;
+};
+export const command = async (conf) => {
+    const { projectRoot, packageJson } = conf.options;
+    const targetOption = conf.get('target');
+    // Handle --target query
+    if (targetOption) {
+        const mainManifest = packageJson.maybeRead(projectRoot);
+        if (!mainManifest) {
+            throw error('No package.json found in project root', {
+                path: projectRoot,
+            });
+        }
+        const graph = actual.load({
+            ...conf.options,
+            mainManifest,
+            monorepo: conf.options.monorepo,
+            loadManifests: true,
+        });
+        const securityArchive = Query.hasSecuritySelectors(targetOption) ?
+            await SecurityArchive.start({
+                nodes: [...graph.nodes.values()],
+            })
+            : undefined;
+        const hostContexts = await createHostContextsMap(conf);
+        const query = new Query({
+            nodes: new Set(graph.nodes.values()),
+            edges: graph.edges,
+            importers: graph.importers,
+            securityArchive,
+            hostContexts,
+        });
+        const { nodes } = await query.search(targetOption, {
+            signal: new AbortController().signal,
+        });
+        const results = [];
+        for (const node of nodes) {
+            if (!node.manifest)
+                continue;
+            const url = getUrlFromManifest(node.manifest);
+            results.push({
+                url,
+                name: node.name /* c8 ignore next */ ?? '(unknown)',
+            });
+        }
+        if (results.length === 0) {
+            throw error('No packages found matching target query', {
+                found: targetOption,
+            });
+        }
+        // If single result, open it
+        if (results.length === 1) {
+            const result = results[0];
+            /* c8 ignore next 3 */
+            if (!result) {
+                throw error('Unexpected empty result');
+            }
+            await urlOpen(result.url);
+            return result;
+        }
+        // Multiple results, return the list
+        return results;
+    }
+    // read the package spec from a positional argument or local package.json
+    const specArg = conf.positionals[0];
+    const manifest = conf.positionals.length === 0 ? packageJson.read(projectRoot)
+        : specArg ?
+            await new PackageInfoClient(conf.options).manifest(Spec.parseArgs(specArg, conf.options))
+            : /* c8 ignore next */ packageJson.read(projectRoot);
+    const url = getUrlFromManifest(manifest);
+    const { name } = manifest;
+    /* c8 ignore start - getUrlFromManifest already validates name */
+    if (!name) {
+        throw error('No package name found');
+    }
+    /* c8 ignore stop */
+    // Open the URL
+    await urlOpen(url);
+    return { url, name };
+};

package/dist/commands/exec-cache.d.ts

@@ -0,0 +1,48 @@
+import type { VlxInfo } from '@vltpkg/vlx';
+import type { LoadedConfig } from '../config/index.ts';
+import type { CommandFn, CommandUsage } from '../index.ts';
+import type { ViewOptions, Views } from '../view.ts';
+import { ViewClass } from '../view.ts';
+export type ExecCacheSubcommands = keyof (typeof usageDef)['subcommands'];
+export declare class ExecCacheView extends ViewClass {
+    constructor(options: ViewOptions, conf: LoadedConfig);
+    stdout(...args: unknown[]): void;
+}
+export declare const views: Views<void | string[] | VlxInfo[]>;
+declare const usageDef: {
+    readonly command: "exec-cache";
+    readonly usage: "<command> [flags]";
+    readonly description: "Work with vlt exec-cache folders";
+    readonly subcommands: {
+        readonly ls: {
+            readonly usage: "";
+            readonly description: "Show previously installed packages used for `vlt exec`.\n                    Key provided can be either the package name, or the full\n                    key.";
+        };
+        readonly delete: {
+            readonly usage: "[<key>...]";
+            readonly description: "Delete previously installed packages used for\n                    `vlt exec`. If no keys are provided, then all entries\n                    will be deleted.";
+        };
+        readonly info: {
+            readonly usage: "<key>";
+            readonly description: "Show extended information about a given `vlt exec`\n                    installation.";
+        };
+        readonly install: {
+            readonly usage: "<spec>...";
+            readonly description: "Install the specified package(s) in the `vlt exec`\n                    central cache location. Metadata info about each\n                    installation will be printed.";
+        };
+    };
+    readonly examples: {
+        readonly ls: {
+            readonly description: "Show all the keys for the installations in the `vlt exec`\n                    cache.";
+        };
+        readonly 'delete typescript': {
+            readonly description: "Delete all versions of typescript installed for vlt exec";
+        };
+        readonly 'info typescript-695bf962': {
+            readonly description: "Show extended info about a specific version of typescript";
+        };
+    };
+};
+export declare const usage: CommandUsage;
+export declare const command: CommandFn<string[] | VlxInfo[]>;
+export {};

package/dist/commands/exec-cache.js

@@ -0,0 +1,145 @@
+import { error } from '@vltpkg/error-cause';
+import { RollbackRemove } from '@vltpkg/rollback-remove';
+import * as vlx from '@vltpkg/vlx';
+import { basename } from 'node:path';
+import { commandUsage } from "../config/usage.js";
+import { stdout } from "../output.js";
+import { ViewClass } from "../view.js";
+let view;
+export class ExecCacheView extends ViewClass {
+    constructor(options, conf) {
+        super(options, conf);
+        view = this;
+    }
+    stdout(...args) {
+        stdout(...args);
+    }
+}
+export const views = {
+    human: ExecCacheView,
+};
+const usageDef = {
+    command: 'exec-cache',
+    usage: '<command> [flags]',
+    description: 'Work with vlt exec-cache folders',
+    subcommands: {
+        ls: {
+            usage: '',
+            description: `Show previously installed packages used for \`vlt exec\`.
+                    Key provided can be either the package name, or the full
+                    key.`,
+        },
+        delete: {
+            usage: '[<key>...]',
+            description: `Delete previously installed packages used for
+                    \`vlt exec\`. If no keys are provided, then all entries
+                    will be deleted.`,
+        },
+        info: {
+            usage: '<key>',
+            description: `Show extended information about a given \`vlt exec\`
+                    installation.`,
+        },
+        install: {
+            usage: '<spec>...',
+            description: `Install the specified package(s) in the \`vlt exec\`
+                    central cache location. Metadata info about each
+                    installation will be printed.`,
+        },
+    },
+    examples: {
+        ls: {
+            description: `Show all the keys for the installations in the \`vlt exec\`
+                    cache.`,
+        },
+        'delete typescript': {
+            description: `Delete all versions of typescript installed for vlt exec`,
+        },
+        'info typescript-695bf962': {
+            description: `Show extended info about a specific version of typescript`,
+        },
+    },
+};
+export const usage = () => commandUsage(usageDef);
+export const command = async (conf) => {
+    const [sub, ...args] = conf.positionals;
+    switch (sub) {
+        case 'ls':
+            return ls(conf, args, view);
+        case 'info':
+            return info(conf, args, view);
+        case 'install':
+            return install(conf, args, view);
+        case 'delete':
+            return deleteEntries(conf, args, view);
+        default: {
+            throw error('Unrecognized exec-cache command', {
+                code: 'EUSAGE',
+                found: sub,
+                validOptions: Object.keys(usageDef.subcommands),
+            });
+        }
+    }
+};
+const install = async (conf, keys, view) => {
+    if (!keys.length) {
+        throw error('Must supply a package spec to install', {
+            code: 'EUSAGE',
+        });
+    }
+    const allowScripts = conf.get('allow-scripts') ?
+        String(conf.get('allow-scripts'))
+        : ':not(*)';
+    return Promise.all(keys.map(async (key) => {
+        const info = await vlx.install(key, {
+            ...conf.options,
+            query: undefined,
+            allowScripts,
+        });
+        view?.stdout(info);
+        return info.path;
+    }));
+};
+const ls = async (_conf, args, view) => {
+    const results = [];
+    for await (const path of vlx.list()) {
+        const key = basename(path);
+        if (args.length && !args.some(a => key.includes(a)))
+            continue;
+        results.push(key);
+        view?.stdout(key);
+    }
+    return results;
+};
+const info = async (conf, keys, view) => {
+    const allowScripts = conf.get('allow-scripts') ?
+        String(conf.get('allow-scripts'))
+        : ':not(*)';
+    const results = [];
+    for await (const key of keys.length ? keys : vlx.list()) {
+        const info = vlx.info(key, {
+            ...conf.options,
+            query: undefined,
+            allowScripts,
+        });
+        results.push(info);
+        view?.stdout(info);
+    }
+    return results;
+};
+const deleteEntries = async (conf, keys, view) => {
+    const allowScripts = conf.get('allow-scripts') ?
+        String(conf.get('allow-scripts'))
+        : ':not(*)';
+    const remover = new RollbackRemove();
+    const removed = (await vlx.delete(keys, remover, {
+        ...conf.options,
+        query: undefined,
+        allowScripts,
+    })).map(path => {
+        view?.stdout(`- ${basename(path)}`);
+        return path;
+    });
+    remover.confirm();
+    return removed;
+};

package/dist/commands/exec-local.d.ts

@@ -0,0 +1,5 @@
+import type { ExecResult } from '../exec-command.ts';
+import type { CommandFn, CommandUsage } from '../index.ts';
+export { views } from '../exec-command.ts';
+export declare const usage: CommandUsage;
+export declare const command: CommandFn<ExecResult>;

package/dist/commands/exec-local.js

@@ -0,0 +1,46 @@
+import { exec, execFG } from '@vltpkg/run';
+import { commandUsage } from "../config/usage.js";
+import { ExecCommand } from "../exec-command.js";
+export { views } from "../exec-command.js";
+export const usage = () => commandUsage({
+    command: 'exec-local',
+    usage: '[command]',
+    description: `Run an arbitrary command, with the local installed packages
+                  first in the PATH. Ie, this will run your locally installed
+                  package bins.
+
+                  If no command is provided, then a shell is spawned in the
+                  current working directory, with the locally installed package
+                  bins first in the PATH.
+
+                  Note that any vlt configs must be specified *before* the
+                  command, as the remainder of the command line options are
+                  provided to the exec process.`,
+    options: {
+        scope: {
+            value: '<query>',
+            description: 'Filter execution targets using a DSS query.',
+        },
+        workspace: {
+            value: '<path|glob>',
+            description: 'Limit execution to matching workspace paths or globs.',
+        },
+        'workspace-group': {
+            value: '<name>',
+            description: 'Limit execution to named workspace groups.',
+        },
+        recursive: {
+            description: 'Run across all selected workspaces.',
+        },
+        'if-present': {
+            description: 'When running across multiple packages, only include packages with matching scripts.',
+        },
+        bail: {
+            description: 'When running across multiple workspaces, stop on first failure.',
+        },
+    },
+});
+export const command = async (conf) => {
+    delete conf.options['script-shell'];
+    return await new ExecCommand(conf, exec, execFG).run();
+};

package/dist/commands/exec.d.ts

@@ -0,0 +1,8 @@
+import type { PromptFn } from '@vltpkg/vlx';
+import type { ExecResult } from '../exec-command.ts';
+import type { CommandFn, CommandUsage } from '../index.ts';
+export { views } from '../exec-command.ts';
+export declare const usage: CommandUsage;
+export declare const prettyPath: (path: string) => string;
+export declare const promptFn: PromptFn;
+export declare const command: CommandFn<ExecResult>;

package/dist/commands/exec.js

@@ -0,0 +1,161 @@
+import { exec, execFG } from '@vltpkg/run';
+import * as vlx from '@vltpkg/vlx';
+import { homedir } from 'node:os';
+import { env, platform } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+import { commandUsage } from "../config/usage.js";
+import { ExecCommand } from "../exec-command.js";
+import { styleTextStdout } from "../output.js";
+export { views } from "../exec-command.js";
+export const usage = () => commandUsage({
+    command: 'exec',
+    usage: '[--package=<pkg>] [--call=<cmd>] [command...]',
+    description: `Run a command defined by a package, installing it
+                  if necessary.
+
+                  If the package specifier is provided explicitly via the
+                  \`--package\` config, then that is what will be used. If
+                  a satisfying instance of the named package exists in the
+                  local \`node_modules\` folder, then that will be used.
+
+                  If \`--package\` is not set, then vlt will attempt to infer
+                  the package to be installed if necessary, in the following
+                  manner:
+
+                  - If the first argument is an executable found in the
+                    \`node_modules/.bin\` folder (ie, provided by an
+                    installed direct dependency), then that will be used.
+                    The search stops, and nothing will be installed.
+                  - Otherwise, vlt attempts to resolve the first argument
+                    as if it was a \`--package\` option, and then swap it
+                    out with the "default" executable provided by that
+                    package.
+
+                  The "default" executable provided by a package is:
+
+                  - If the package provides a single executable string in the
+                    \`bin\` field, then that is the executable to use.
+                  - Otherwise, if there is a \`bin\` with the same name
+                    as the package (or just the portion after the \`/\` in
+                    the case of scoped packages), then that will be used.
+
+                  If the appropriate excutable cannot be determined, then
+                  an error will be raised.
+
+                  At no point will \`vlt exec\` change the locally installed
+                  dependencies. Any installs it performs is done in vlt's XDG
+                  data directory.
+    `,
+    examples: {
+        '--package typescript@5 tsc': {
+            description: 'Run tsc provided by typescript version 5',
+        },
+        'eslint src/file.js': {
+            description: 'Run the default bin provided by eslint',
+        },
+        'eslint@9.24 src/file.js': {
+            description: 'Run the default bin provided by eslint version 9.24',
+        },
+        'create-react-app --call="echo $PWD"': {
+            description: 'Install create-react-app and run an arbitrary command with its bins in PATH',
+        },
+        '--call="echo $PWD" --scope=":workspace"': {
+            description: 'Run an arbitrary command in the context of each workspace',
+        },
+    },
+    options: {
+        package: {
+            value: '<specifier>',
+            description: 'Explicitly set the package to search for bins.',
+        },
+        call: {
+            value: '<cmd>',
+            description: 'Run an arbitrary command string after installing any specified package and adding its bins to PATH.',
+        },
+        'allow-scripts': {
+            value: '<query>',
+            description: 'Filter which packages are allowed to run lifecycle scripts using DSS query syntax.',
+        },
+        scope: {
+            value: '<query>',
+            description: 'Filter execution targets using a DSS query.',
+        },
+        workspace: {
+            value: '<path|glob>',
+            description: 'Limit execution to matching workspace paths or globs.',
+        },
+        'workspace-group': {
+            value: '<name>',
+            description: 'Limit execution to named workspace groups.',
+        },
+        recursive: {
+            description: 'Run across all selected workspaces.',
+        },
+        'if-present': {
+            description: 'When running across multiple packages, only include packages with matching scripts.',
+        },
+        bail: {
+            description: 'When running across multiple workspaces, stop on first failure.',
+        },
+        'script-shell': {
+            value: '<shell>',
+            description: 'The shell to use for --call commands and script execution.',
+        },
+    },
+});
+const HOME = homedir();
+export const prettyPath = (path) => path.startsWith(HOME) ? `~${path.substring(HOME.length)}` : path;
+export const promptFn = async (pkgSpec, path, resolution) => {
+    const response = await createInterface(process.stdin, process.stdout).question(`About to install: ${styleTextStdout(['bgWhiteBright', 'black', 'bold'], String(pkgSpec))}
+from: ${styleTextStdout(['bgWhiteBright', 'black', 'bold'], resolution)}
+into: ${styleTextStdout(['bgWhiteBright', 'black', 'bold'], prettyPath(path))}
+Is this ok? (y) `);
+    process.stdin.pause();
+    return response;
+};
+export const command = async (conf) => {
+    /* c8 ignore start */
+    const allowScripts = conf.get('allow-scripts') ?
+        String(conf.get('allow-scripts'))
+        : ':not(*)';
+    /* c8 ignore stop */
+    const callOption = conf.get('call');
+    if (callOption) {
+        // Install any specified package and add its bins to PATH, but don't
+        // use its default executable - the --call string is the command to run.
+        // Only install when a package is explicitly defined (via --package flag
+        // or as a positional argument). Don't prompt for confirmation since the
+        // user's explicit --call command implies consent.
+        const pkgOption = conf.get('package') ?? conf.positionals[0];
+        if (pkgOption) {
+            await vlx.resolve([], {
+                ...conf.options,
+                package: pkgOption,
+                query: undefined,
+                allowScripts,
+            });
+        }
+        // Determine the shell to use for the --call command
+        const shell = conf.get('script-shell') ??
+            env.SHELL ??
+            /* c8 ignore next */
+            (platform === 'win32' ? 'cmd.exe' : '/bin/sh');
+        // cmd.exe uses '/c', all other shells use '-c'
+        /* c8 ignore next */
+        const shellFlag = shell === 'cmd.exe' ? '/c' : '-c';
+        // Replace positionals with [shell, shellFlag, callOption]
+        conf.positionals.splice(0, conf.positionals.length, shell, shellFlag, callOption);
+    }
+    else {
+        const arg0 = await vlx.resolve(conf.positionals, {
+            ...conf.options,
+            query: undefined,
+            allowScripts,
+        }, promptFn);
+        if (arg0)
+            conf.positionals[0] = arg0;
+    }
+    // now we have arg0! let's gooooo!!
+    delete conf.options['script-shell'];
+    return await new ExecCommand(conf, exec, execFG).run();
+};

package/dist/commands/help.d.ts

@@ -0,0 +1,3 @@
+import type { CommandFn, CommandUsage } from '../load-command.ts';
+export declare const usage: CommandUsage;
+export declare const command: CommandFn<string>;

package/dist/commands/help.js

@@ -0,0 +1,43 @@
+import { error } from '@vltpkg/error-cause';
+import { commandUsage } from "../config/usage.js";
+import { loadCommand } from "../load-command.js";
+import { getCommand } from "../config/definition.js";
+import { generateDefaultHelp, generateFullHelp, } from "../custom-help.js";
+export const usage = () => commandUsage({
+    command: 'help',
+    usage: '[<command>]',
+    description: 'Print the full help output for the CLI, or help for a specific command',
+    examples: {
+        '': { description: 'Show general CLI help' },
+        install: { description: 'Show help for the install command' },
+        run: { description: 'Show help for the run command' },
+    },
+    options: {
+        all: {
+            description: 'Show all commands, bins, and flags.',
+        },
+    },
+});
+export const command = async (conf) => {
+    // If no positional arguments, show general help
+    if (conf.positionals.length === 0) {
+        // Check for color support (prefer explicit config, fall back to TTY detection)
+        const colors = conf.values.color ?? process.stdout.isTTY;
+        // Use full custom help if --all flag is set
+        if (conf.values.all) {
+            return generateFullHelp(colors);
+        }
+        return generateDefaultHelp(colors);
+    }
+    // Get the command name from the first positional argument
+    const cmdName = conf.positionals[0];
+    const canonicalCmd = getCommand(cmdName);
+    if (!canonicalCmd) {
+        throw error(`Unknown command: ${cmdName}`, {
+            found: cmdName,
+            code: 'EUSAGE',
+        });
+    }
+    const command = await loadCommand(canonicalCmd);
+    return command.usage().usage();
+};

package/dist/commands/init.d.ts

@@ -0,0 +1,7 @@
+import type { InitFileResults } from '@vltpkg/init';
+import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const usage: CommandUsage;
+export declare const views: {
+    readonly human: (results: InitFileResults | InitFileResults[]) => string;
+};
+export declare const command: CommandFn<InitFileResults | InitFileResults[]>;