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

package/dist/custom-help.js

@@ -198,6 +198,14 @@ const allCommands = [
         showByDefault: true,
         defaultOrder: 3,
     },
+    {
+        name: 'registry',
+        aliases: [],
+        args: '<alias> <command>',
+        desc: 'Run an account command against a named registry',
+        showByDefault: true,
+        defaultOrder: 9,
+    },
     {
         name: 'repo',
         aliases: [],
@@ -220,6 +228,14 @@ const allCommands = [
         desc: 'Run a script &/or fallback to executing a binary',
         showByDefault: false,
     },
+    {
+        name: 'setup',
+        aliases: [],
+        args: '[<account>]',
+        desc: 'Configure your vlt.io account registries',
+        showByDefault: true,
+        defaultOrder: 0,
+    },
     {
         name: 'token',
         aliases: [],
@@ -348,7 +364,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'],

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/require-registry.d.ts

@@ -0,0 +1,48 @@
+import type { RegistryCandidate } from './select-registry.ts';
+import type { LoadedConfig } from './config/index.ts';
+/**
+ * There is no default registry. This is the single message used
+ * everywhere a registry is required but missing.
+ */
+export declare const missingRegistryError: () => Error;
+/**
+ * Multiple registries are configured and none was selected. Used in
+ * non-interactive contexts where we cannot prompt and there is no
+ * `default-registry-alias` to fall back to.
+ */
+export declare const ambiguousRegistryError: (candidates: RegistryCandidate[]) => Error;
+/**
+ * Resolve a named registry alias to its URL, throwing an `ECONFIG`
+ * error (listing the known aliases) when the alias is not configured.
+ */
+export declare const resolveRegistryAlias: (conf: LoadedConfig, alias: string) => string;
+/**
+ * Whether the current config provides a registry a `needsRegistry`
+ * command could act against without prompting for setup. True when an
+ * explicit `--registry` URL is set or the user has configured at least
+ * one non-default registry alias. Kept consistent with
+ * {@link resolveRegistry} so the pre-command gate never rejects a config
+ * the resolver would otherwise accept or prompt for.
+ */
+export declare const hasConfiguredRegistry: (conf: LoadedConfig) => boolean;
+/**
+ * Synchronous, non-interactive registry resolution used by
+ * programmatic callers. Precedence: explicit alias > `--registry`
+ * scalar > single configured alias > `default-registry-alias`. Throws
+ * when nothing is configured or the choice is ambiguous.
+ */
+export declare const requireRegistry: (conf: LoadedConfig, alias?: string) => string;
+/**
+ * Resolve the registry a command should act against.
+ *
+ * Precedence: explicit `alias` (from `vlt registry <alias> <cmd>`) >
+ * `--registry` URL scalar > the single configured alias. When multiple
+ * aliases are configured and none was chosen, prompt interactively on a
+ * TTY, otherwise fall back to `default-registry-alias`, else error.
+ */
+export declare const resolveRegistry: (conf: LoadedConfig, { alias, interactive, input, output, }?: {
+    alias?: string;
+    interactive?: boolean;
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}) => Promise<string>;

package/dist/require-registry.js

@@ -0,0 +1,122 @@
+import { error } from '@vltpkg/error-cause';
+import { defaultRegistries } from '@vltpkg/spec';
+import { selectRegistry } from "./select-registry.js";
+/**
+ * There is no default registry. This is the single message used
+ * everywhere a registry is required but missing.
+ */
+export const missingRegistryError = () => error([
+    'Missing registry configuration.',
+    '',
+    'vlt has no default registry. Run `vlt setup` to get configured.',
+    '',
+    'See https://docs.vlt.sh/cli for other ways to set a registry.',
+].join('\n'), { code: 'ECONFIG' });
+/**
+ * Multiple registries are configured and none was selected. Used in
+ * non-interactive contexts where we cannot prompt and there is no
+ * `default-registry-alias` to fall back to.
+ */
+export const ambiguousRegistryError = (candidates) => error([
+    'Multiple registries are configured; specify which one to use.',
+    '',
+    'Run `vlt registry <alias> <command>` with one of:',
+    ...candidates.map(c => `  ${c.alias} -> ${c.url}`),
+].join('\n'), {
+    code: 'ECONFIG',
+    validOptions: candidates.map(c => c.alias),
+});
+/**
+ * Resolve a named registry alias to its URL, throwing an `ECONFIG`
+ * error (listing the known aliases) when the alias is not configured.
+ */
+export const resolveRegistryAlias = (conf, alias) => {
+    const url = conf.options.registries[alias];
+    if (!url) {
+        throw error(`Unknown registry alias: ${alias}`, {
+            code: 'ECONFIG',
+            found: alias,
+            validOptions: Object.keys(conf.options.registries),
+        });
+    }
+    return url;
+};
+/**
+ * The registries the user has actually configured, when no explicit
+ * `--registry` URL is set. Order follows the `registries` config (which
+ * preserves insertion order).
+ *
+ * Built-in defaults (eg `gh`) are excluded so they don't implicitly
+ * satisfy "a registry is configured" for account/auth commands. A
+ * built-in alias the user has overridden to a different URL counts as
+ * configured. Built-in aliases can still be targeted explicitly via
+ * `vlt registry <alias> <cmd>` (which resolves through
+ * {@link resolveRegistryAlias}).
+ */
+const gatherCandidates = (conf) => {
+    const builtins = defaultRegistries;
+    return Object.entries(conf.options.registries)
+        .filter(([alias, url]) => builtins[alias] !== url)
+        .map(([alias, url]) => ({ alias, url }));
+};
+/**
+ * Whether the current config provides a registry a `needsRegistry`
+ * command could act against without prompting for setup. True when an
+ * explicit `--registry` URL is set or the user has configured at least
+ * one non-default registry alias. Kept consistent with
+ * {@link resolveRegistry} so the pre-command gate never rejects a config
+ * the resolver would otherwise accept or prompt for.
+ */
+export const hasConfiguredRegistry = (conf) => !!conf.options.registry || gatherCandidates(conf).length > 0;
+/**
+ * Synchronous, non-interactive registry resolution used by
+ * programmatic callers. Precedence: explicit alias > `--registry`
+ * scalar > single configured alias > `default-registry-alias`. Throws
+ * when nothing is configured or the choice is ambiguous.
+ */
+export const requireRegistry = (conf, alias) => {
+    if (alias !== undefined)
+        return resolveRegistryAlias(conf, alias);
+    const { registry } = conf.options;
+    if (registry)
+        return registry;
+    const candidates = gatherCandidates(conf);
+    const [first, second] = candidates;
+    if (!first)
+        throw missingRegistryError();
+    if (!second)
+        return first.url;
+    const defaultUrl = conf.options.registries[conf.options['default-registry-alias']];
+    if (defaultUrl)
+        return defaultUrl;
+    throw ambiguousRegistryError(candidates);
+};
+/**
+ * Resolve the registry a command should act against.
+ *
+ * Precedence: explicit `alias` (from `vlt registry <alias> <cmd>`) >
+ * `--registry` URL scalar > the single configured alias. When multiple
+ * aliases are configured and none was chosen, prompt interactively on a
+ * TTY, otherwise fall back to `default-registry-alias`, else error.
+ */
+export const resolveRegistry = async (conf, { alias, interactive = process.stdin.isTTY, input, output, } = {}) => {
+    if (alias !== undefined)
+        return resolveRegistryAlias(conf, alias);
+    const { registry } = conf.options;
+    if (registry)
+        return registry;
+    const candidates = gatherCandidates(conf);
+    const [first, second] = candidates;
+    if (!first)
+        throw missingRegistryError();
+    if (!second)
+        return first.url;
+    const defaultAlias = conf.options['default-registry-alias'];
+    if (interactive) {
+        return selectRegistry(candidates, { defaultAlias, input, output });
+    }
+    const defaultUrl = conf.options.registries[defaultAlias];
+    if (defaultUrl)
+        return defaultUrl;
+    throw ambiguousRegistryError(candidates);
+};

package/dist/select-registry.d.ts

@@ -0,0 +1,23 @@
+/** A configured registry the user can act against. */
+export type RegistryCandidate = {
+    /** the configured alias name (a key in `registries`) */
+    alias: string;
+    /** the resolved registry URL */
+    url: string;
+};
+export type SelectStreams = {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+};
+/**
+ * Interactively prompt the user to choose one of the configured
+ * registries. `defaultAlias` (when present in `candidates`) is
+ * pre-selected so pressing enter accepts it.
+ *
+ * Streams are injectable so tests can drive the prompt deterministically.
+ */
+export declare const selectRegistry: (candidates: RegistryCandidate[], { defaultAlias, input, output, }?: {
+    defaultAlias?: string;
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}) => Promise<string>;

package/dist/select-registry.js

@@ -0,0 +1,40 @@
+import { error } from '@vltpkg/error-cause';
+import { createInterface } from 'node:readline/promises';
+/**
+ * Interactively prompt the user to choose one of the configured
+ * registries. `defaultAlias` (when present in `candidates`) is
+ * pre-selected so pressing enter accepts it.
+ *
+ * Streams are injectable so tests can drive the prompt deterministically.
+ */
+export const selectRegistry = async (candidates, { defaultAlias, input = process.stdin, output = process.stdout, } = {}) => {
+    const defaultIndex = Math.max(candidates.findIndex(c => c.alias === defaultAlias), 0);
+    const fallback = candidates[defaultIndex] ?? candidates[0];
+    if (!fallback) {
+        throw error('No registries to select from', { code: 'ECONFIG' });
+    }
+    const rl = createInterface({ input, output });
+    try {
+        output.write('Multiple registries are configured. Select one:\n');
+        for (const [i, c] of candidates.entries()) {
+            const marker = i === defaultIndex ? ' (default)' : '';
+            output.write(`  ${i + 1}) ${c.alias} -> ${c.url}${marker}\n`);
+        }
+        const answer = (await rl.question(`Registry [${defaultIndex + 1}]: `)).trim();
+        if (!answer)
+            return fallback.url;
+        const choice = Number(answer);
+        const picked = candidates[choice - 1];
+        if (!Number.isInteger(choice) || !picked) {
+            throw error('Invalid registry selection', {
+                found: answer,
+                validOptions: candidates.map((_, i) => String(i + 1)),
+                code: 'EUSAGE',
+            });
+        }
+        return picked.url;
+    }
+    finally {
+        rl.close();
+    }
+};

package/dist/verbose-log.d.ts

@@ -0,0 +1,31 @@
+import type { Events } from '@vltpkg/output';
+/**
+ * Diagnostic logging levels, ordered from least to most verbose.
+ * Mirrors the `loglevel` option in the config definition.
+ */
+export type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'verbose' | 'debug';
+/** True when the given level should emit per-request logging. */
+export declare const isVerbose: (level: LogLevel) => boolean;
+/** The subset of `styleText` color names this module applies. */
+export type StyleColor = 'green' | 'red' | 'gray';
+/**
+ * Minimal signature compatible with the `styleText` helpers exported by
+ * `./output.ts` (which accept a wider set of format names). Defaults to an
+ * identity function so this module can be tested without color support.
+ */
+export type StyleFn = (format: StyleColor, s: string) => string;
+/**
+ * Format a single `request` event into a human-readable log line.
+ * Exported for testing.
+ */
+export declare const formatRequestEvent: (event: Events["request"], style?: StyleFn) => string;
+/**
+ * Subscribe to registry request events and stream them to `write` when
+ * the configured `level` is `verbose` or higher. The `start` event is only
+ * logged at `debug` level to avoid duplicate lines (each network request
+ * also emits a `complete`/`304` line with its status and duration).
+ *
+ * Returns a cleanup function that detaches the subscription. When `level`
+ * is below `verbose`, nothing is subscribed and the cleanup is a no-op.
+ */
+export declare const startRequestLog: (level: LogLevel, write: (line: string) => void, style?: StyleFn) => (() => void);

package/dist/verbose-log.js

@@ -0,0 +1,62 @@
+import { emitter } from '@vltpkg/output';
+const rank = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    verbose: 4,
+    debug: 5,
+};
+/** True when the given level should emit per-request logging. */
+export const isVerbose = (level) => rank[level] >= rank.verbose;
+const isDebug = (level) => rank[level] >= rank.debug;
+const identityStyle = (_f, s) => s;
+const tagStyle = (state, statusCode) => {
+    switch (state) {
+        case 'cache':
+        case 'stale':
+        case '304':
+            return 'green';
+        case 'start':
+            return 'gray';
+        case 'complete':
+            return statusCode !== undefined && statusCode >= 400 ?
+                'red'
+                : 'green';
+    }
+};
+/**
+ * Format a single `request` event into a human-readable log line.
+ * Exported for testing.
+ */
+export const formatRequestEvent = (event, style = identityStyle) => {
+    const { url, state, method = 'GET', statusCode, durationMs } = event;
+    // For completed network requests show the status code rather than the
+    // literal word "complete"; everything else shows the cache/fetch state.
+    const tag = state === 'complete' ? String(statusCode ?? '') : state;
+    const duration = durationMs === undefined ? '' : (style('gray', ` (${durationMs}ms)`));
+    return `${style(tagStyle(state, statusCode), tag.padEnd(8))} ${method} ${String(url)}${duration}`;
+};
+/**
+ * Subscribe to registry request events and stream them to `write` when
+ * the configured `level` is `verbose` or higher. The `start` event is only
+ * logged at `debug` level to avoid duplicate lines (each network request
+ * also emits a `complete`/`304` line with its status and duration).
+ *
+ * Returns a cleanup function that detaches the subscription. When `level`
+ * is below `verbose`, nothing is subscribed and the cleanup is a no-op.
+ */
+export const startRequestLog = (level, write, style = identityStyle) => {
+    if (!isVerbose(level))
+        return () => { };
+    const debug = isDebug(level);
+    const handler = (event) => {
+        // At verbose level, skip the `start` event so each request produces a
+        // single completion line; at debug level, show it too.
+        if (event.state === 'start' && !debug)
+            return;
+        write(formatRequestEvent(event, style));
+    };
+    emitter.on('request', handler);
+    return () => emitter.off('request', handler);
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/cli-sdk",
   "description": "The source for the vlt CLI",
-  "version": "1.0.0-rc.32",
+  "version": "1.0.0-rc.33",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -14,30 +14,30 @@
   },
   "dependencies": {
     "@resvg/resvg-wasm": "^2.6.2",
-    "@vltpkg/config": "1.0.0-rc.32",
-    "@vltpkg/dep-id": "1.0.0-rc.32",
-    "@vltpkg/dot-prop": "1.0.0-rc.32",
-    "@vltpkg/error-cause": "1.0.0-rc.32",
-    "@vltpkg/git": "1.0.0-rc.32",
-    "@vltpkg/graph": "1.0.0-rc.32",
-    "@vltpkg/graph-run": "1.0.0-rc.32",
-    "@vltpkg/init": "1.0.0-rc.32",
-    "@vltpkg/output": "1.0.0-rc.32",
-    "@vltpkg/package-info": "1.0.0-rc.32",
-    "@vltpkg/package-json": "1.0.0-rc.32",
-    "@vltpkg/promise-spawn": "1.0.0-rc.32",
-    "@vltpkg/query": "1.0.0-rc.32",
-    "@vltpkg/registry-client": "1.0.0-rc.32",
-    "@vltpkg/rollback-remove": "1.0.0-rc.32",
-    "@vltpkg/run": "1.0.0-rc.32",
-    "@vltpkg/security-archive": "1.0.0-rc.32",
-    "@vltpkg/spec": "1.0.0-rc.32",
-    "@vltpkg/types": "1.0.0-rc.32",
-    "@vltpkg/url-open": "1.0.0-rc.32",
-    "@vltpkg/vlt-json": "1.0.0-rc.32",
-    "@vltpkg/vlx": "1.0.0-rc.32",
-    "@vltpkg/workspaces": "1.0.0-rc.32",
-    "@vltpkg/xdg": "1.0.0-rc.32",
+    "@vltpkg/config": "1.0.0-rc.33",
+    "@vltpkg/dep-id": "1.0.0-rc.33",
+    "@vltpkg/dot-prop": "1.0.0-rc.33",
+    "@vltpkg/error-cause": "1.0.0-rc.33",
+    "@vltpkg/git": "1.0.0-rc.33",
+    "@vltpkg/graph": "1.0.0-rc.33",
+    "@vltpkg/graph-run": "1.0.0-rc.33",
+    "@vltpkg/init": "1.0.0-rc.33",
+    "@vltpkg/output": "1.0.0-rc.33",
+    "@vltpkg/package-info": "1.0.0-rc.33",
+    "@vltpkg/package-json": "1.0.0-rc.33",
+    "@vltpkg/promise-spawn": "1.0.0-rc.33",
+    "@vltpkg/query": "1.0.0-rc.33",
+    "@vltpkg/registry-client": "1.0.0-rc.33",
+    "@vltpkg/rollback-remove": "1.0.0-rc.33",
+    "@vltpkg/run": "1.0.0-rc.33",
+    "@vltpkg/security-archive": "1.0.0-rc.33",
+    "@vltpkg/spec": "1.0.0-rc.33",
+    "@vltpkg/types": "1.0.0-rc.33",
+    "@vltpkg/url-open": "1.0.0-rc.33",
+    "@vltpkg/vlt-json": "1.0.0-rc.33",
+    "@vltpkg/vlx": "1.0.0-rc.33",
+    "@vltpkg/workspaces": "1.0.0-rc.33",
+    "@vltpkg/xdg": "1.0.0-rc.33",
     "ansi-to-pre": "^1.0.6",
     "beautiful-mermaid": "^1.1.3",
     "chalk": "^5.6.2",
@@ -120,5 +120,12 @@
   ],
   "keywords": [
     "vltpkg"
-  ]
+  ],
+  "bugs": [
+    {
+      "type": "link",
+      "url": "https://github.com/vltpkg/vltpkg/issues"
+    }
+  ],
+  "homepage": "https://github.com/vltpkg/vltpkg/tree/main/src/cli-sdk#readme"
 }