@vltpkg/cli-sdk 1.0.0-rc.3 → 1.0.0-rc.31

package/dist/commands/deprecate.js

@@ -0,0 +1,139 @@
+import { error } from '@vltpkg/error-cause';
+import { PackageInfoClient } from '@vltpkg/package-info';
+import { RegistryClient } from '@vltpkg/registry-client';
+import { Spec } from '@vltpkg/spec';
+import { satisfies } from '@vltpkg/semver';
+import { asError } from '@vltpkg/types';
+import { commandUsage } from "../config/usage.js";
+export const usage = () => commandUsage({
+    command: 'deprecate',
+    usage: '<pkg>[@<version>] <message>',
+    description: `Update the npm registry entry for a package, providing a
+                  deprecation warning to all who attempt to install it.
+
+                  It works on version ranges as well as specific versions,
+                  so you can un-deprecate a previously deprecated package by
+                  specifying the version range with an empty string as the
+                  message.`,
+    examples: {
+        'my-package "this package is no longer maintained"': {
+            description: 'Deprecate all versions of a package',
+        },
+        'my-package@"<0.2.0" "critical bug, please update"': {
+            description: 'Deprecate specific versions',
+        },
+        'my-package ""': {
+            description: 'Un-deprecate a package',
+        },
+    },
+    options: {
+        registry: {
+            value: '<url>',
+            description: 'The registry to update.',
+        },
+        otp: {
+            description: `Provide an OTP to use when deprecating a package.`,
+            value: '<otp>',
+        },
+    },
+});
+export const views = {
+    human: result => {
+        if (result.message === '') {
+            return `✅ Un-deprecated ${result.name}@${result.version} (${result.versions.length} version${result.versions.length === 1 ? '' : 's'})`;
+        }
+        return `⚠️ Deprecated ${result.name}@${result.version} (${result.versions.length} version${result.versions.length === 1 ? '' : 's'}): ${result.message}`;
+    },
+    json: r => r,
+};
+export const command = async (conf) => {
+    const specArg = conf.positionals[0];
+    const message = conf.positionals[1];
+    if (!specArg) {
+        throw error('deprecate requires a package spec and message argument', {
+            code: 'EUSAGE',
+        });
+    }
+    if (message === undefined) {
+        throw error('deprecate requires a message argument', {
+            code: 'EUSAGE',
+        });
+    }
+    const spec = Spec.parseArgs(specArg, conf.options);
+    const { name } = spec;
+    if (!name || name === '(unknown)') {
+        throw error('could not determine package name from spec', {
+            found: specArg,
+        });
+    }
+    const { registry, otp } = conf.options;
+    const registryUrl = new URL(registry);
+    // Fetch the current packument
+    const pic = new PackageInfoClient(conf.options);
+    const packument = await pic.packument(spec);
+    // Determine which versions match the spec
+    const versionRange = spec.bareSpec;
+    const matchedVersions = [];
+    for (const version of Object.keys(packument.versions)) {
+        if (!versionRange || satisfies(version, versionRange)) {
+            matchedVersions.push(version);
+        }
+    }
+    if (matchedVersions.length === 0) {
+        throw error('no versions found matching the spec', {
+            found: specArg,
+            wanted: Object.keys(packument.versions),
+        });
+    }
+    // Build the update payload with deprecated field set on matched versions
+    const versions = {};
+    for (const version of matchedVersions) {
+        const manifest = packument.versions[version];
+        /* c8 ignore next */
+        if (!manifest)
+            continue;
+        versions[version] = {
+            ...manifest,
+            ...(message === '' ?
+                { deprecated: undefined }
+                : { deprecated: message }),
+        };
+    }
+    const body = {
+        _id: name,
+        name,
+        versions,
+    };
+    const rc = new RegistryClient(conf.options);
+    const packageUrl = new URL(name.startsWith('@') ? name.replace('/', '%2F') : name, registryUrl);
+    let response;
+    try {
+        response = await rc.request(packageUrl, {
+            method: 'PUT',
+            headers: {
+                'content-type': 'application/json',
+                'npm-auth-type': 'web',
+                'npm-command': 'deprecate',
+            },
+            body: JSON.stringify(body),
+            otp,
+        });
+    }
+    catch (err) {
+        throw error('failed to update deprecation status', {
+            cause: asError(err),
+        });
+    }
+    if (response.statusCode !== 200 && response.statusCode !== 201) {
+        throw error('failed to update deprecation status', {
+            url: packageUrl,
+            response,
+        });
+    }
+    return {
+        name,
+        version: versionRange || '*',
+        message,
+        versions: matchedVersions,
+    };
+};

package/dist/commands/dist-tag.d.ts

@@ -0,0 +1,21 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const usage: CommandUsage;
+export type DistTagLsResult = {
+    id: string;
+    tags: Record<string, string>;
+};
+export type DistTagAddResult = {
+    id: string;
+    tag: string;
+    version: string;
+};
+export type DistTagRmResult = {
+    id: string;
+    tag: string;
+};
+export type CommandResult = DistTagLsResult | DistTagAddResult | DistTagRmResult;
+export declare const views: {
+    readonly human: (result: CommandResult) => string;
+    readonly json: (r: CommandResult) => CommandResult;
+};
+export declare const command: CommandFn<CommandResult>;

package/dist/commands/dist-tag.js

@@ -0,0 +1,177 @@
+import { error } from '@vltpkg/error-cause';
+import { RegistryClient } from '@vltpkg/registry-client';
+import { Spec } from '@vltpkg/spec';
+import { commandUsage } from "../config/usage.js";
+export const usage = () => commandUsage({
+    command: 'dist-tag',
+    usage: [
+        'add <pkg>@<version> [<tag>]',
+        'rm <pkg> <tag>',
+        'ls [<pkg>]',
+    ],
+    description: `Manage distribution tags for a package.
+
+    Distribution tags (dist-tags) provide aliases for package versions,
+    allowing users to install specific versions using tag names instead
+    of version numbers. The most common tag is \`latest\`, which is used
+    by default when no tag is specified during install.`,
+    subcommands: {
+        add: {
+            usage: '<pkg>@<version> [<tag>]',
+            description: 'Tag the specified version of a package with the given tag, or "latest" if unspecified.',
+        },
+        rm: {
+            usage: '<pkg> <tag>',
+            description: 'Remove a dist-tag from a package.',
+        },
+        ls: {
+            usage: '[<pkg>]',
+            description: 'List all dist-tags for a package, defaulting to the package in the current directory.',
+        },
+    },
+    options: {
+        registry: {
+            value: '<url>',
+            description: 'Registry URL to manage dist-tags for.',
+        },
+        identity: {
+            value: '<name>',
+            description: 'Identity namespace used to look up auth tokens.',
+        },
+    },
+});
+const isLsResult = (r) => 'tags' in r;
+const isAddResult = (r) => 'version' in r;
+export const views = {
+    human: result => {
+        if (isLsResult(result)) {
+            const entries = Object.entries(result.tags);
+            if (entries.length === 0)
+                return 'No dist-tags found.';
+            return entries
+                .map(([tag, version]) => `${tag}: ${version}`)
+                .join('\n');
+        }
+        if (isAddResult(result)) {
+            return `+${result.tag}: ${result.id}@${result.version}`;
+        }
+        return `-${result.tag}: ${result.id}`;
+    },
+    json: r => r,
+};
+/**
+ * Build the dist-tags API URL for a package.
+ * Uses the `/-/package/{name}/dist-tags` endpoint.
+ */
+const distTagsUrl = (name, registry, tag) => {
+    const encoded = name.startsWith('@') ? name.replace('/', '%2f') : name;
+    const path = tag ?
+        `-/package/${encoded}/dist-tags/${encodeURIComponent(tag)}`
+        : `-/package/${encoded}/dist-tags`;
+    return new URL(path, registry);
+};
+const readPackageName = (positional, conf) => {
+    if (positional) {
+        const spec = Spec.parseArgs(positional, conf.options);
+        return spec.name;
+    }
+    const manifest = conf.options.packageJson.maybeRead(conf.projectRoot);
+    if (manifest?.name)
+        return manifest.name;
+    throw error('Could not determine package name', {
+        code: 'EUSAGE',
+    });
+};
+export const command = async (conf) => {
+    const [sub, ...args] = conf.positionals;
+    if (!sub) {
+        throw error('dist-tag command requires a subcommand', {
+            code: 'EUSAGE',
+            validOptions: ['add', 'rm', 'remove', 'ls', 'list'],
+        });
+    }
+    const rc = new RegistryClient(conf.options);
+    const registry = conf.options.registry;
+    switch (sub) {
+        case 'add': {
+            const specArg = args[0];
+            if (!specArg) {
+                throw error('dist-tag add requires a package@version argument', {
+                    code: 'EUSAGE',
+                });
+            }
+            const spec = Spec.parseArgs(specArg, conf.options);
+            const name = spec.name;
+            const version = spec.bareSpec;
+            if (!version) {
+                throw error('dist-tag add requires a version in the spec', {
+                    code: 'EUSAGE',
+                    found: specArg,
+                });
+            }
+            const tag = args[1] ?? conf.options.tag;
+            const url = distTagsUrl(name, registry, tag);
+            const response = await rc.request(url, {
+                method: 'PUT',
+                headers: {
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(version),
+                useCache: false,
+            });
+            if (response.statusCode < 200 || response.statusCode >= 300) {
+                throw error('Failed to add dist-tag', {
+                    url,
+                    response,
+                });
+            }
+            return { id: name, tag, version };
+        }
+        case 'rm':
+        case 'remove': {
+            const pkgArg = args[0];
+            const tag = args[1];
+            if (!pkgArg || !tag) {
+                throw error('dist-tag rm requires a package name and tag', {
+                    code: 'EUSAGE',
+                });
+            }
+            const name = readPackageName(pkgArg, conf);
+            const url = distTagsUrl(name, registry, tag);
+            const response = await rc.request(url, {
+                method: 'DELETE',
+                useCache: false,
+            });
+            if (response.statusCode < 200 || response.statusCode >= 300) {
+                throw error('Failed to remove dist-tag', {
+                    url,
+                    response,
+                });
+            }
+            return { id: name, tag };
+        }
+        case 'ls':
+        case 'list': {
+            const name = readPackageName(args[0], conf);
+            const url = distTagsUrl(name, registry);
+            const response = await rc.request(url, {
+                useCache: false,
+            });
+            if (response.statusCode < 200 || response.statusCode >= 300) {
+                throw error('Failed to list dist-tags', {
+                    url,
+                    response,
+                });
+            }
+            const tags = response.json();
+            return { id: name, tags };
+        }
+        default: {
+            throw error('Invalid dist-tag subcommand', {
+                found: sub,
+                validOptions: ['add', 'rm', 'remove', 'ls', 'list'],
+                code: 'EUSAGE',
+            });
+        }
+    }
+};

package/dist/{esm/commands → commands}/docs.d.ts

@@ -15,4 +15,3 @@ export declare const views: {
 };
 export declare const command: CommandFn<CommandResult>;
 export {};
-//# sourceMappingURL=docs.d.ts.map

package/dist/{esm/commands → commands}/docs.js

@@ -67,9 +67,9 @@ const getUrlFromManifest = (manifest) => {
             }
         }
     }
-    // Fallback to npmjs.com package page
+    // Fallback to vlt.io package page
     if (!url) {
-        url = `https://www.npmjs.com/package/${name}`;
+        url = `https://vlt.io/explore/npm/${name}/overview`;
     }
     return url;
 };
@@ -151,4 +151,3 @@ export const command = async (conf) => {
     await urlOpen(url);
     return { url, name };
 };
-//# sourceMappingURL=docs.js.map

package/dist/{esm/commands → commands}/exec-cache.d.ts

@@ -46,4 +46,3 @@ declare const usageDef: {
 export declare const usage: CommandUsage;
 export declare const command: CommandFn<string[] | VlxInfo[]>;
 export {};
-//# sourceMappingURL=exec-cache.d.ts.map

package/dist/{esm/commands → commands}/exec-cache.js

@@ -143,4 +143,3 @@ const deleteEntries = async (conf, keys, view) => {
     remover.confirm();
     return removed;
 };
-//# sourceMappingURL=exec-cache.js.map

package/dist/{esm/commands → commands}/exec-local.d.ts

@@ -3,4 +3,3 @@ import type { CommandFn, CommandUsage } from '../index.ts';
 export { views } from '../exec-command.ts';
 export declare const usage: CommandUsage;
 export declare const command: CommandFn<ExecResult>;
-//# sourceMappingURL=exec-local.d.ts.map

package/dist/{esm/commands → commands}/exec-local.js

@@ -16,9 +16,31 @@ export const usage = () => commandUsage({
                   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();
 };
-//# sourceMappingURL=exec-local.js.map

package/dist/{esm/commands → commands}/exec.d.ts

@@ -6,4 +6,3 @@ export declare const usage: CommandUsage;
 export declare const prettyPath: (path: string) => string;
 export declare const promptFn: PromptFn;
 export declare const command: CommandFn<ExecResult>;
-//# sourceMappingURL=exec.d.ts.map

package/dist/{esm/commands → commands}/exec.js

@@ -1,6 +1,7 @@
 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";
@@ -8,14 +9,14 @@ import { styleTextStdout } from "../output.js";
 export { views } from "../exec-command.js";
 export const usage = () => commandUsage({
     command: 'exec',
-    usage: '[--package=<pkg>] [command...]',
+    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_mnodules\` folder, then that will be used.
+                  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
@@ -55,6 +56,51 @@ export const usage = () => commandUsage({
         '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();
@@ -73,15 +119,43 @@ export const command = async (conf) => {
         String(conf.get('allow-scripts'))
         : ':not(*)';
     /* c8 ignore stop */
-    const arg0 = await vlx.resolve(conf.positionals, {
-        ...conf.options,
-        query: undefined,
-        allowScripts,
-    }, promptFn);
-    if (arg0)
-        conf.positionals[0] = arg0;
+    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();
 };
-//# sourceMappingURL=exec.js.map

package/dist/{esm/commands → commands}/help.d.ts

@@ -1,4 +1,3 @@
 import type { CommandFn, CommandUsage } from '../load-command.ts';
 export declare const usage: CommandUsage;
 export declare const command: CommandFn<string>;
-//# sourceMappingURL=help.d.ts.map

package/dist/{esm/commands → commands}/help.js

@@ -12,6 +12,11 @@ export const usage = () => commandUsage({
         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
@@ -36,4 +41,3 @@ export const command = async (conf) => {
     const command = await loadCommand(canonicalCmd);
     return command.usage().usage();
 };
-//# sourceMappingURL=help.js.map

package/dist/{esm/commands → commands}/init.d.ts

@@ -5,4 +5,3 @@ export declare const views: {
     readonly human: (results: InitFileResults | InitFileResults[]) => string;
 };
 export declare const command: CommandFn<InitFileResults | InitFileResults[]>;
-//# sourceMappingURL=init.d.ts.map

package/dist/{esm/commands → commands}/init.js

@@ -2,13 +2,22 @@ import { mkdirSync } from 'node:fs';
 import { relative, resolve } from 'node:path';
 import { minimatch } from 'minimatch';
 import { init } from '@vltpkg/init';
+import { install } from '@vltpkg/graph';
 import { load, save } from '@vltpkg/vlt-json';
 import { assertWSConfig, asWSConfig } from '@vltpkg/workspaces';
 import { commandUsage } from "../config/usage.js";
 export const usage = () => commandUsage({
     command: 'init',
     usage: '',
-    description: `Create a new package.json file in the current directory.`,
+    description: `Initialize a new project in the current directory.
+                  Creates a package.json, a .gitignore, and installs
+                  dependencies so the project is ready to use immediately.`,
+    options: {
+        workspace: {
+            value: '<path|glob>',
+            description: 'Create package.json files in matching workspaces.',
+        },
+    },
 });
 // TODO: colorize the JSON if config.options.color
 export const views = {
@@ -17,17 +26,20 @@ export const views = {
         // if results is an array, it means multiple workspaces were initialized
         if (Array.isArray(results)) {
             for (const result of results) {
-                for (const [type, { path }] of Object.entries(result)) {
-                    output.push(`Wrote ${type} to ${path}:`);
+                for (const [type, value] of Object.entries(result)) {
+                    output.push(`Wrote ${type} to ${value.path}`);
                 }
             }
         }
         else {
             // otherwise, it's a single result
-            for (const [type, { path, data }] of Object.entries(results)) {
-                output.push(`Wrote ${type} to ${path}:
-
-${JSON.stringify(data, null, 2)}`);
+            for (const [type, value] of Object.entries(results)) {
+                if ('data' in value) {
+                    output.push(`Wrote ${type} to ${value.path}:\n\n${JSON.stringify(value.data, null, 2)}`);
+                }
+                else {
+                    output.push(`Wrote ${type} to ${value.path}`);
+                }
             }
         }
         output.push(`\nModify/add properties using \`vlt pkg\`. For example:
@@ -37,6 +49,11 @@ ${JSON.stringify(data, null, 2)}`);
     },
 };
 export const command = async (conf) => {
+    /* c8 ignore start */
+    const allowScripts = conf.get('allow-scripts') ?
+        String(conf.get('allow-scripts'))
+        : ':not(*)';
+    /* c8 ignore stop */
     if (conf.values.workspace?.length) {
         const workspacesConfig = load('workspaces', assertWSConfig);
         const parsedWSConfig = asWSConfig(workspacesConfig ?? {});
@@ -78,7 +95,7 @@ export const command = async (conf) => {
             else {
                 // otherwise we assume it's an Record<string, string[]> object
                 // and we'll add the new workspaces to the `packages` keys
-                workspaces = (workspacesConfig ?? {});
+                workspaces = workspacesConfig ?? {};
                 // if the `packages` key is not being used
                 if (!workspaces.packages) {
                     workspaces.packages = addToConfig;
@@ -104,8 +121,12 @@ export const command = async (conf) => {
             // finally, we add the new workspaces to the config file
             save('workspaces', workspaces);
         }
+        // run install to set up node_modules and vlt-lock.json
+        await install({ ...conf.options, allowScripts });
         return results;
     }
-    return init({ cwd: process.cwd() });
+    const result = await init({ cwd: process.cwd() });
+    // run install to set up node_modules and vlt-lock.json
+    await install({ ...conf.options, allowScripts });
+    return result;
 };
-//# sourceMappingURL=init.js.map

package/dist/{esm/commands → commands}/install/reporter.d.ts

@@ -8,4 +8,3 @@ export declare class InstallReporter extends ViewClass {
     }): Promise<undefined>;
     error(err: unknown): void;
 }
-//# sourceMappingURL=reporter.d.ts.map

package/dist/{esm/commands → commands}/install/reporter.js

@@ -91,4 +91,3 @@ export class InstallReporter extends ViewClass {
         this.#instance?.unmount(asError(err));
     }
 }
-//# sourceMappingURL=reporter.js.map