@vltpkg/cli-sdk 1.0.0-rc.32 → 1.0.0-rc.34

package/dist/config/definition.js

@@ -40,9 +40,11 @@ const canonicalCommands = {
     profile: 'profile',
     publish: 'publish',
     query: 'query',
+    registry: 'registry',
     repo: 'repo',
     'run-exec': 'run-exec',
     run: 'run',
+    setup: 'setup',
     token: 'token',
     uninstall: 'uninstall',
     unpublish: 'unpublish',
@@ -155,26 +157,46 @@ export const definition = j
     .opt({
     registry: {
         hint: 'url',
-        default: 'https://registry.npmjs.org/',
         description: `Sets the registry for fetching packages, when no registry
                     is explicitly set on a specifier.
 
                     For example, \`express@latest\` will be resolved by looking
                     up the metadata from this registry.
 
-                    Note that alias specifiers starting with \`npm:\` will
-                    still map to \`https://registry.npmjs.org/\` if this is
-                    changed, unless the a new mapping is created via the
-                    \`--registries\` option.
+                    There is **no default**. When unset, bare specifiers fall
+                    back to the registry alias named by
+                    \`--default-registry-alias\` (\`npm\` by default). If that
+                    alias is also unconfigured, commands that need a registry
+                    fail with a config error. Run \`vlt setup\` (or
+                    \`vlt login\`) to configure one.
+
+                    See https://docs.vlt.sh/cli
+      `,
+    },
+    'default-registry-alias': {
+        hint: 'name',
+        default: 'npm',
+        description: `The name of the registry alias (a key in
+                    \`--registries\`) that bare specifiers (e.g.
+                    \`express@latest\`) and transitive dependencies without an
+                    explicit registry protocol resolve through, when neither
+                    \`--registry\` nor a matching \`--scoped-registries\` entry
+                    applies.
+
+                    Defaults to \`npm\`. Note that the \`npm\` alias has **no**
+                    built-in URL -- it must be configured (for example via
+                    \`vlt setup\`, which points it at your vlt.io registry),
+                    otherwise bare specifiers will have no registry to resolve
+                    against.
       `,
     },
 })
     .optList({
     registries: {
         hint: 'name=url',
-        description: `Specify named registry hosts by their prefix. To set the
-                    default registry used for non-namespaced specifiers,
-                    use the \`--registry\` option.
+        description: `Specify named registry hosts by their prefix. To choose
+                    which alias is used for non-namespaced specifiers, use the
+                    \`--default-registry-alias\` option.
 
                     Prefixes can be used as a package alias. For example:
 
@@ -182,9 +204,10 @@ export const definition = j
                     vlt --registries loc=http://reg.local install foo@loc:foo@1.x
                     \`\`\`
 
-                    By default, the public npm registry is registered to the
-                    \`npm:\` prefix. It is not recommended to change this
-                    mapping in most cases.
+                    There is **no** built-in \`npm\` registry URL; the \`npm\`
+                    alias must be configured (e.g. via \`vlt setup\`) before it
+                    can be used. The \`gh\` and \`jsr\` aliases have built-in
+                    defaults that can be overridden here.
                     `,
     },
     'scoped-registries': {
@@ -554,6 +577,41 @@ export const definition = j
             'silent',
         ],
     },
+})
+    .opt({
+    loglevel: {
+        hint: 'level',
+        default: 'info',
+        description: `Sets the verbosity of diagnostic logging written to
+                    stderr (registry requests, warnings, etc). This is
+                    independent of \`--view\`, which controls a command's
+                    result output on stdout.
+
+                    - silent: No diagnostic logging.
+                    - error: Only errors.
+                    - warn: Errors and warnings.
+                    - info: Default. High-level progress.
+                    - verbose: Adds per-request logging (each registry URL
+                      with its cache/stale/fetch outcome and status code).
+                    - debug: Everything, including low-level detail.
+
+                    \`--verbose\` is shorthand for \`--loglevel=verbose\`.`,
+        validOptions: [
+            'silent',
+            'error',
+            'warn',
+            'info',
+            'verbose',
+            'debug',
+        ],
+    },
+})
+    .flag({
+    verbose: {
+        description: `Shorthand for \`--loglevel=verbose\`. Streams each
+                    registry request to stderr with its cache/fetch outcome
+                    and status code, useful for debugging request behavior.`,
+    },
 })
     .optList({
     'dashboard-root': {
@@ -568,6 +626,12 @@ export const definition = j
         description: `Save installed packages to a package.json file as
                     devDependencies`,
     },
+    'save-exact': {
+        short: 'E',
+        description: `Save installed packages to package.json with an exact
+                    version rather than using the default semver range
+                    operator (e.g. \`1.2.3\` instead of \`^1.2.3\`).`,
+    },
     'save-optional': {
         short: 'O',
         description: `Save installed packages to a package.json file as
@@ -584,6 +648,15 @@ export const definition = j
                     devDependencies or optionalDependencies, but you want to
                     move it to be a non-optional production dependency.`,
     },
+})
+    .opt({
+    'save-prefix': {
+        description: `The version prefix to use when saving dependencies to
+                    package.json (e.g. \`^\`, \`~\`, \`>=\`, or empty string
+                    for exact versions). Defaults to \`^\`.
+                    Ignored when \`--save-exact\` is set.`,
+        default: '^',
+    },
 })
     .opt({
     'expect-results': {

package/dist/config/index.js

@@ -212,6 +212,12 @@ export class Config {
         else
             this.command = getCommand(p.values['fallback-command']);
         Object.assign(this, p);
+        // `--verbose` is shorthand for `--loglevel=verbose`. Only apply it
+        // when loglevel is still at its default so an explicit `--loglevel`
+        // always wins.
+        if (p.values.verbose && p.values.loglevel === 'info') {
+            p.values.loglevel = 'verbose';
+        }
         /* c8 ignore start - unpossible */
         if (!isParsed(this))
             throw error('failed to parse config');

package/dist/custom-help.js

@@ -1,5 +1,6 @@
 import { loadPackageJson } from 'package-json-from-dist';
 import chalk from 'chalk';
+import { commandAliases } from "./config/definition.js";
 const { version } = loadPackageJson(import.meta.filename, process.env.__VLT_INTERNAL_CLI_PACKAGE_JSON);
 // Custom yellow color: #FFE15D
 const customYellow = chalk.hex('#FFE15D');
@@ -42,227 +43,176 @@ const makeStyler = (colors) => {
         return styledText;
     };
 };
-// Single source of truth for all commands with metadata
-const allCommands = [
-    {
-        name: 'bugs',
-        aliases: [],
+/**
+ * Help metadata for every command target in the command registry. Using a
+ * record keyed by CommandName makes missing or stale entries a type error;
+ * aliases are derived separately from the registry below.
+ */
+const commandHelp = {
+    access: {
+        args: '<command> [<args>]',
+        desc: 'Manage package access and team permissions',
+    },
+    bugs: {
         args: '[<spec>]',
         desc: 'Open the bug tracker for a package',
-        showByDefault: false,
     },
-    {
-        name: 'build',
-        aliases: ['b'],
+    build: {
         args: '<selector>',
         desc: 'Build packages with lifecycle scripts',
-        showByDefault: true,
         defaultOrder: 4,
     },
-    {
-        name: 'cache',
-        aliases: [],
+    cache: {
         args: '[add|ls|info|clean|delete|delete-before|delete-all]',
         desc: 'Manage the package cache',
-        showByDefault: false,
     },
-    {
-        name: 'ci',
-        aliases: [],
+    ci: {
         args: '',
         desc: 'Clean install (frozen lockfile)',
-        showByDefault: false,
     },
-    {
-        name: 'config',
-        aliases: [],
+    config: {
         args: '[get|pick|list|set|delete|edit|location]',
         desc: 'Get or set configuration',
-        showByDefault: false,
     },
-    {
-        name: 'create',
-        aliases: [],
+    create: {
         args: '<initializer> [args...]',
         desc: 'Create a new project from a template',
-        showByDefault: false,
     },
-    {
-        name: 'docs',
-        aliases: [],
+    deprecate: {
+        args: '<pkg>[@<version>] <message>',
+        desc: 'Deprecate a package or version range',
+    },
+    'dist-tag': {
+        args: '[add|rm|ls] [<args>]',
+        desc: 'Manage package distribution tags',
+    },
+    docs: {
         args: '',
         desc: 'Open the docs of the current project',
-        showByDefault: false,
     },
-    {
-        name: 'exec',
-        aliases: ['x'],
+    exec: {
         args: '<executable>',
         desc: 'Execute a package bin',
-        showByDefault: true,
         defaultOrder: 6,
     },
-    {
-        name: 'exec-cache',
-        aliases: ['xc'],
+    'exec-cache': {
         args: '[ls|delete|info|install]',
         desc: 'Manage the exec cache',
-        showByDefault: false,
     },
-    {
-        name: 'exec-local',
-        aliases: ['xl'],
+    'exec-local': {
         args: '<command>',
         desc: 'Execute a local package bin',
-        showByDefault: false,
     },
-    {
-        name: 'help',
-        aliases: ['h', '?'],
+    help: {
         args: '[<command>]',
         desc: 'Show help for a command',
-        showByDefault: false,
     },
-    {
-        name: 'init',
-        aliases: [],
+    init: {
         args: '',
         desc: 'Initialize a new project',
-        showByDefault: true,
         defaultOrder: 1,
     },
-    {
-        name: 'install',
-        aliases: ['i', 'add'],
+    install: {
         args: '[<package>...]',
         desc: 'Install dependencies',
-        showByDefault: true,
         defaultOrder: 2,
     },
-    {
-        name: 'list',
-        aliases: ['ls'],
+    list: {
         args: '',
         desc: 'List installed packages',
-        showByDefault: false,
     },
-    {
-        name: 'login',
-        aliases: [],
+    login: {
         args: '',
         desc: 'Authenticate with a registry',
-        showByDefault: false,
     },
-    {
-        name: 'logout',
-        aliases: [],
+    logout: {
         args: '',
         desc: 'Log out from a registry',
-        showByDefault: false,
     },
-    {
-        name: 'pack',
-        aliases: [],
+    pack: {
         args: '',
         desc: 'Create a tarball from a package',
-        showByDefault: false,
     },
-    {
-        name: 'ping',
-        aliases: [],
+    ping: {
         args: '[<registry-alias>]',
         desc: 'Ping configured registries',
-        showByDefault: false,
     },
-    {
-        name: 'pkg',
-        aliases: ['p'],
+    pkg: {
         args: '<command>',
         desc: 'Manage package metadata',
-        showByDefault: true,
         defaultOrder: 7,
     },
-    {
-        name: 'publish',
-        aliases: ['pub'],
+    profile: {
+        args: '<command> [<args>]',
+        desc: 'Get or set registry profile properties',
+    },
+    publish: {
         args: '',
         desc: 'Publish package to registry',
-        showByDefault: true,
         defaultOrder: 8,
     },
-    {
-        name: 'query',
-        aliases: ['q'],
+    query: {
         args: '<selector>',
         desc: 'Query for packages in the project',
-        showByDefault: true,
         defaultOrder: 3,
     },
-    {
-        name: 'repo',
-        aliases: [],
+    registry: {
+        args: '<alias> <command>',
+        desc: 'Run an account command against a named registry',
+        defaultOrder: 9,
+    },
+    repo: {
         args: '[<spec>]',
         desc: 'Open the repository page for a package',
-        showByDefault: false,
     },
-    {
-        name: 'run',
-        aliases: ['r'],
+    run: {
         args: '<script>',
         desc: 'Run a script defined in package.json',
-        showByDefault: true,
         defaultOrder: 5,
     },
-    {
-        name: 'run-exec',
-        aliases: ['rx'],
+    'run-exec': {
         args: '<script>',
         desc: 'Run a script &/or fallback to executing a binary',
-        showByDefault: false,
     },
-    {
-        name: 'token',
-        aliases: [],
+    setup: {
+        args: '[<account>]',
+        desc: 'Configure your vlt.io account registries',
+        defaultOrder: 0,
+    },
+    token: {
         args: '[add|rm]',
         desc: 'Manage authentication tokens',
-        showByDefault: false,
     },
-    {
-        name: 'uninstall',
-        aliases: ['rm'],
+    uninstall: {
         args: '[<package>...]',
         desc: 'Remove dependencies',
-        showByDefault: false,
     },
-    {
-        name: 'unpublish',
-        aliases: [],
+    unpublish: {
         args: '<pkg>[@<version>]',
         desc: 'Remove a package from the registry',
-        showByDefault: false,
     },
-    {
-        name: 'update',
-        aliases: ['u'],
+    update: {
         args: '',
         desc: 'Update package versions to latest in-range',
-        showByDefault: false,
     },
-    {
-        name: 'version',
-        aliases: [],
+    version: {
         args: '<increment>',
         desc: 'Bump package version',
-        showByDefault: false,
     },
-    {
-        name: 'whoami',
-        aliases: [],
+    view: {
+        args: '<pkg>[@<version>] [<field>]',
+        desc: 'View registry information about a package',
+    },
+    whoami: {
         args: '',
         desc: 'Display the current user',
-        showByDefault: false,
     },
-];
+};
+const allCommands = Object.entries(commandHelp).map(([name, metadata]) => ({
+    name,
+    aliases: commandAliases.get(name) ?? [],
+    ...metadata,
+}));
 /**
  * Generates the custom default help output for vlt
  */
@@ -270,8 +220,8 @@ export const generateDefaultHelp = (colors = false) => {
     const s = makeStyler(colors);
     // Get default commands and sort by defaultOrder
     const defaultCommands = allCommands
-        .filter(cmd => cmd.showByDefault)
-        .sort((a, b) => (a.defaultOrder || 0) - (b.defaultOrder || 0));
+        .filter(cmd => cmd.defaultOrder !== undefined)
+        .sort((a, b) => (a.defaultOrder ?? 0) - (b.defaultOrder ?? 0));
     // Generate commands with tighter alias spacing but proper table structure
     const commandsSection = defaultCommands
         .map(cmd => {
@@ -282,7 +232,7 @@ export const generateDefaultHelp = (colors = false) => {
         const nameColumn = cmd.name.padEnd(10);
         // Consistent args column (14 chars)
         const argsColumn = cmd.args.padEnd(16);
-        return `  ${s('dim', aliasColumn)}${s(['yellow', 'bold'], nameColumn)}${s('dim', argsColumn)}${cmd.desc}`;
+        return `  ${s('dim', aliasColumn)}${s(['yellow', 'bold'], nameColumn)}${s('dim', argsColumn)} ${cmd.desc}`;
     })
         .join('\n');
     return `${s(['bold'], '⚡️ vlt')} ${s('dim', '/vōlt/')} next-gen package management ${s('dim', `v${version}`)}
@@ -318,6 +268,8 @@ export const generateFullHelp = (colors = false) => {
     const s = makeStyler(colors);
     // Use all commands sorted alphabetically
     const commands = [...allCommands].sort((a, b) => a.name.localeCompare(b.name));
+    const aliasLabels = commands.map(cmd => cmd.aliases.length ? `${cmd.aliases.join(', ')},` : '');
+    const aliasWidth = Math.max(...aliasLabels.map(label => label.length));
     // Define only globally applicable flags (alphabetically sorted by long name)
     const flags = [
         {
@@ -348,7 +300,7 @@ export const generateFullHelp = (colors = false) => {
             shorts: [],
             long: 'registry',
             args: '<url>',
-            desc: 'Override default registry',
+            desc: 'Set the registry to resolve packages against',
         },
         {
             shorts: ['v'],
@@ -372,17 +324,14 @@ export const generateFullHelp = (colors = false) => {
         if (firstLetter !== lastFirstLetter && index > 0) {
             commandsSection += '\n';
         }
-        // Fixed width columns for proper alignment with space after comma
-        const aliasColumn = cmd.aliases.length > 0 ?
-            (cmd.aliases.join(', ') + ', ').padEnd(9)
-            : '         ';
+        const aliasColumn = aliasLabels[index]?.padEnd(aliasWidth) ?? '';
         const nameColumn = cmd.name.padEnd(12);
         // Truncate args if longer than 16 chars and add ellipsis
         const truncatedArgs = cmd.args.length > 16 ?
             cmd.args.substring(0, 13) + '...'
             : cmd.args;
         const argsColumn = truncatedArgs.padEnd(16);
-        commandsSection += `${s('dim', aliasColumn)}${s(['yellow', 'bold'], nameColumn)}${s('dim', argsColumn)}${cmd.desc}`;
+        commandsSection += `  ${s('dim', aliasColumn)} ${s(['yellow', 'bold'], nameColumn)} ${s('dim', argsColumn)} ${cmd.desc}`;
         if (index < commands.length - 1) {
             commandsSection += '\n';
         }

package/dist/index.js

@@ -66,6 +66,10 @@ const run = async () => {
         }
         return process.exit(process.exitCode || 1);
     }
+    if (vlt.command === 'registry') {
+        const { dispatchRegistry } = await import("./commands/registry.js");
+        await dispatchRegistry(vlt);
+    }
     const command = await loadCommand(vlt.command);
     await outputCommand(command, vlt, { start, vltVersion: version });
 };

package/dist/load-command.d.ts

@@ -11,5 +11,11 @@ export type Command<T> = {
     command: CommandFn<T>;
     usage: CommandUsage;
     views: Views<T>;
+    /**
+     * Set to `true` by commands that hit a registry or resolve registry
+     * specs. There is no default registry, so `outputCommand()` fails
+     * early with an `ECONFIG` error when one of these runs unconfigured.
+     */
+    needsRegistry?: boolean;
 };
 export declare const loadCommand: <T>(command: Commands[keyof Commands] | undefined) => Promise<Command<T>>;

package/dist/output.js

@@ -2,9 +2,11 @@ import { formatWithOptions, styleText as utilStyleText, } from 'node:util';
 import { createSupportsColor } from 'supports-color';
 import { defaultView } from "./config/definition.js";
 import { printErr, formatOptions } from "./print-err.js";
+import { hasConfiguredRegistry, missingRegistryError, } from "./require-registry.js";
 import { isViewClass } from "./view.js";
 import { generateDefaultHelp, generateFullHelp, } from "./custom-help.js";
 import { flush as flushTelemetry, trackCommand, trackError, } from "./telemetry.js";
+import { startRequestLog } from "./verbose-log.js";
 /* c8 ignore start - CI env detection is a best-effort heuristic */
 const isCI = () => !!(process.env.CI ||
     process.env.GITHUB_ACTIONS ||
@@ -90,7 +92,7 @@ const startView = (conf, opts, views, { start } = { start: Date.now() }) => {
 export const outputCommand = async (cliCommand, conf, { start, vltVersion } = {
     start: Date.now(),
 }) => {
-    const { usage, views, command } = cliCommand;
+    const { usage, views, command, needsRegistry } = cliCommand;
     const stdoutColor = conf.values.color ?? supportsColor(process.stdout);
     const stderrColor = conf.values.color ?? supportsColor(process.stderr);
     if (conf.values.help) {
@@ -111,13 +113,24 @@ export const outputCommand = async (cliCommand, conf, { start, vltVersion } = {
     if (stderrColor)
         styleTextStderr = styleText;
     /* c8 ignore stop */
+    // Stream per-request diagnostics to stderr when `--loglevel` is verbose
+    // or higher (e.g. via `--verbose`). No-op otherwise.
+    const stopRequestLog = startRequestLog(conf.values.loglevel, line => stderr(line), styleTextStderr);
     const { onDone, onError } = startView(conf, 
     // assume views will always output to stdout so use color support from there
     { colors: stdoutColor }, views, { start });
     const telemetryEnabled = conf.values.telemetry;
     const commandName = conf.command;
     try {
+        // checked here rather than in run() so that the missing-registry
+        // error is rendered, tracked and exited like any other command
+        // error, and so that the `--help` return above still works when
+        // nothing is configured.
+        if (needsRegistry && !hasConfiguredRegistry(conf)) {
+            throw missingRegistryError();
+        }
         const output = await onDone(await command(conf));
+        stopRequestLog();
         const duration_ms = Date.now() - start;
         trackCommand({
             command: commandName,
@@ -145,6 +158,7 @@ export const outputCommand = async (cliCommand, conf, { start, vltVersion } = {
         await flushTelemetry();
     }
     catch (err) {
+        stopRequestLog();
         onError?.(err);
         process.exitCode ||= 1;
         const duration_ms = Date.now() - start;

package/dist/print-err.js

@@ -13,6 +13,15 @@ export const formatOptions = {
 };
 const isNonEmptyString = (v) => !!v && typeof v === 'string';
 const formatURL = (v, format) => v instanceof URL ? v.toString() : /* c8 ignore next */ format(v);
+// True when `v` overrides the default `Object.prototype.toString`, i.e.
+// stringifying it yields something meaningful (like a `Spec` → `next@*`)
+// rather than `[object Object]`.
+const hasCustomToString = (v) => isObject(v) && v.toString !== Object.prototype.toString;
+// Render a value that has a meaningful custom `toString()` (such as a
+// `Spec`, e.g. `next@*`) as a concise string rather than dumping its
+// entire internal structure via util.inspect. Falls back to `format`
+// for plain values/objects.
+const formatToString = (v, format) => hasCustomToString(v) ? v.toString() : format(v);
 const formatArray = (v, format, joiner = ', ') => Array.isArray(v) ? v.join(joiner) : /* c8 ignore next */ format(v);
 export const indent = (lines, num = 2) => lines
     .split('\n')
@@ -147,7 +156,7 @@ const printCode = (err, usage, stderr, format) => {
                 stderr(indent(`While fetching: ${formatURL(url, format)}`));
             }
             if (spec) {
-                stderr(indent(`To satisfy: ${format(spec)}`));
+                stderr(indent(`To satisfy: ${formatToString(spec, format)}`));
             }
             if (from) {
                 stderr(indent(`From: ${format(from)}`));

package/dist/registry-error-message.d.ts

@@ -0,0 +1,2 @@
+import type { CacheEntry } from '@vltpkg/registry-client';
+export declare const registryErrorMessage: (response: CacheEntry) => string;

package/dist/registry-error-message.js

@@ -0,0 +1,29 @@
+import { STATUS_CODES } from 'node:http';
+export const registryErrorMessage = (response) => {
+    const statusMessage = STATUS_CODES[response.statusCode];
+    const status = `${response.statusCode}${statusMessage ? ` ${statusMessage}` : ''}`;
+    let text;
+    try {
+        text = response.text().trim();
+    }
+    catch {
+        return status;
+    }
+    if (!text)
+        return status;
+    let detail = text;
+    try {
+        const body = JSON.parse(text);
+        if (body &&
+            typeof body === 'object' &&
+            'error' in body &&
+            typeof body.error === 'string' &&
+            body.error) {
+            detail = body.error;
+        }
+    }
+    catch {
+        // A non-JSON response body is itself the most useful error detail.
+    }
+    return `${status} — ${detail}`;
+};