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

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.34",
   "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.34",
+    "@vltpkg/dep-id": "1.0.0-rc.34",
+    "@vltpkg/dot-prop": "1.0.0-rc.34",
+    "@vltpkg/error-cause": "1.0.0-rc.34",
+    "@vltpkg/git": "1.0.0-rc.34",
+    "@vltpkg/graph": "1.0.0-rc.34",
+    "@vltpkg/graph-run": "1.0.0-rc.34",
+    "@vltpkg/init": "1.0.0-rc.34",
+    "@vltpkg/output": "1.0.0-rc.34",
+    "@vltpkg/package-info": "1.0.0-rc.34",
+    "@vltpkg/package-json": "1.0.0-rc.34",
+    "@vltpkg/promise-spawn": "1.0.0-rc.34",
+    "@vltpkg/query": "1.0.0-rc.34",
+    "@vltpkg/registry-client": "1.0.0-rc.34",
+    "@vltpkg/rollback-remove": "1.0.0-rc.34",
+    "@vltpkg/run": "1.0.0-rc.34",
+    "@vltpkg/security-archive": "1.0.0-rc.34",
+    "@vltpkg/spec": "1.0.0-rc.34",
+    "@vltpkg/types": "1.0.0-rc.34",
+    "@vltpkg/url-open": "1.0.0-rc.34",
+    "@vltpkg/vlt-json": "1.0.0-rc.34",
+    "@vltpkg/vlx": "1.0.0-rc.34",
+    "@vltpkg/workspaces": "1.0.0-rc.34",
+    "@vltpkg/xdg": "1.0.0-rc.34",
     "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"
 }