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

package/dist/commands/setup.d.ts

@@ -0,0 +1,25 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+/** Where users sign up for / log into a vlt.io account. */
+export declare const VLT_SIGNUP_URL = "https://www.vlt.io";
+/** Base URL that per-account registries live under. */
+export declare const VLT_REGISTRY_BASE = "https://registry.vlt.io";
+/**
+ * The registry aliases that every vlt.io account is provisioned with.
+ * `npm` is the {@link https://docs.vlt.sh | default bare-spec alias}.
+ */
+export declare const accountRegistries: readonly ["npm", "main"];
+/** Build the per-account registry URL for a given registry name. */
+export declare const accountRegistryURL: (account: string, name: string) => string;
+export type SetupResult = {
+    /** the account slug the registries were built for */
+    account: string;
+    /** which config file the registries were written to */
+    which: 'user' | 'project';
+    /** the alias -> url map that was staged into config */
+    registries: Record<string, string>;
+};
+export declare const views: {
+    readonly human: (result: SetupResult) => string;
+};
+export declare const usage: CommandUsage;
+export declare const command: CommandFn<SetupResult>;

package/dist/commands/setup.js

@@ -0,0 +1,142 @@
+import { error } from '@vltpkg/error-cause';
+import { RegistryClient } from '@vltpkg/registry-client';
+import { defaultRegistries } from '@vltpkg/spec';
+import { createInterface } from 'node:readline/promises';
+import { commandUsage } from "../config/usage.js";
+import { stdout } from "../output.js";
+/** Where users sign up for / log into a vlt.io account. */
+export const VLT_SIGNUP_URL = 'https://www.vlt.io';
+/** Base URL that per-account registries live under. */
+export const VLT_REGISTRY_BASE = 'https://registry.vlt.io';
+/**
+ * The registry aliases that every vlt.io account is provisioned with.
+ * `npm` is the {@link https://docs.vlt.sh | default bare-spec alias}.
+ */
+export const accountRegistries = ['npm', 'main'];
+/** Build the per-account registry URL for a given registry name. */
+export const accountRegistryURL = (account, name) => `${VLT_REGISTRY_BASE}/${encodeURIComponent(account)}/${name}/`;
+/** Ensure a registry URL ends with a single trailing slash. */
+const normalizeRegistryURL = (url) => url.endsWith('/') ? url : `${url}/`;
+export const views = {
+    human: (result) => {
+        const lines = [
+            `Configured ${Object.keys(result.registries).length} registry ${Object.keys(result.registries).length === 1 ?
+                'alias'
+                : 'aliases'} for "${result.account}" in ${result.which} config:`,
+        ];
+        for (const [name, url] of Object.entries(result.registries)) {
+            lines.push(`  ${name} -> ${url}`);
+        }
+        lines.push('', 'You can now install packages, e.g.:', '  vlt install <pkg>');
+        return lines.join('\n');
+    },
+};
+export const usage = () => commandUsage({
+    command: 'setup',
+    usage: '[<account>]',
+    description: `Configure the registry aliases for your vlt.io account so
+                  that \`vlt install\` and \`vlx\` work out of the box.
+
+                  Sign up or log in at ${VLT_SIGNUP_URL} first. The wizard
+                  authenticates against your account and writes the
+                  \`npm\` and \`main\` registry aliases (and any additional
+                  aliases you add) to your user \`vlt.json\`.`,
+    options: {
+        config: {
+            value: '<user | project>',
+            description: 'Which config file to write to. Defaults to `user`; pass ' +
+                '`--config=project` to write to the project `vlt.json`.',
+        },
+        registries: {
+            value: '<name=url>',
+            description: 'Additional registry aliases to stage non-interactively. ' +
+                'Combine with `--yes` to run setup unattended.',
+        },
+        yes: {
+            description: 'Skip interactive prompts (requires <account> and does not ' +
+                'open a browser for authentication).',
+        },
+    },
+});
+export const command = async (conf) => {
+    const yes = !!conf.get('yes');
+    const which = conf.get('config') === 'project' ? 'project' : 'user';
+    let rl;
+    const ask = async (question) => {
+        rl ??= createInterface(process.stdin, process.stdout);
+        return (await rl.question(question)).trim();
+    };
+    try {
+        stdout(`Sign up or log in at ${VLT_SIGNUP_URL} before continuing.`);
+        // 1. resolve the account slug
+        let account = conf.positionals[0]?.trim();
+        if (!account) {
+            if (yes) {
+                throw error('An account slug is required in non-interactive mode. ' +
+                    'Pass it as an argument: `vlt setup <account> --yes`.', { code: 'ECONFIG' });
+            }
+            account = await ask('vlt.io account or organization slug: ');
+            if (!account) {
+                throw error('No account slug provided.', { code: 'ECONFIG' });
+            }
+        }
+        // 2. stage the two known account registries
+        const registries = {};
+        for (const name of accountRegistries) {
+            registries[name] = accountRegistryURL(account, name);
+        }
+        // 3. merge any user-supplied registry aliases (skip built-in defaults)
+        const builtinRegistries = defaultRegistries;
+        for (const [name, url] of Object.entries(conf.options.registries)) {
+            if (builtinRegistries[name] === url)
+                continue;
+            registries[name] = normalizeRegistryURL(url);
+        }
+        const rc = new RegistryClient(conf.options);
+        // 4. authenticate against the account registries (interactive only)
+        if (!yes) {
+            const doAuth = await ask('Authenticate with your vlt.io account now? (Y/n) ');
+            if (!/^n/i.test(doAuth)) {
+                for (const name of accountRegistries) {
+                    stdout(`Authenticating against the "${name}" registry...`);
+                    await rc.login(accountRegistryURL(account, name));
+                }
+            }
+            // 5. offer to add further custom aliases
+            for (;;) {
+                const more = await ask('Add another registry alias? (y/N) ');
+                if (!/^y/i.test(more))
+                    break;
+                const name = await ask('  alias name: ');
+                if (!name) {
+                    stdout('  alias name is required, skipping.');
+                    continue;
+                }
+                if (name in registries) {
+                    stdout(`  alias "${name}" is already staged, skipping.`);
+                    continue;
+                }
+                const url = await ask('  registry url: ');
+                if (!url) {
+                    stdout('  registry url is required, skipping.');
+                    continue;
+                }
+                const normalized = normalizeRegistryURL(url);
+                registries[name] = normalized;
+                const auth = await ask(`  authenticate against "${name}" now? (y/N) `);
+                if (/^y/i.test(auth)) {
+                    await rc.login(normalized);
+                }
+            }
+        }
+        // 6. persist the staged registries (merged, not clobbered)
+        await conf.addConfigToFile(which, { registries });
+        return { account, which, registries };
+    }
+    finally {
+        if (rl) {
+            rl.close();
+            process.stdin.pause();
+        }
+    }
+};

package/dist/commands/token.d.ts

@@ -23,6 +23,7 @@ export type TokenListResult = {
     identity: string;
     registries: RegistryTokens[];
 };
+export declare const needsRegistry = true;
 export declare const usage: CommandUsage;
 export declare const views: {
     readonly human: (r: TokenListResult | void) => string | undefined;

package/dist/commands/token.js

@@ -2,10 +2,15 @@ import { error } from '@vltpkg/error-cause';
 import { deleteToken, getKC, getToken, normalizeRegistryKey, registryBase, RegistryClient, setToken, } from '@vltpkg/registry-client';
 import { commandUsage } from "../config/usage.js";
 import { readPassword } from "../read-password.js";
+import { requireRegistry } from "../require-registry.js";
+export const needsRegistry = true;
 export const usage = () => commandUsage({
     command: 'token',
     usage: ['list', 'add', 'rm'],
-    description: `Manage registry authentication tokens in the vlt keychain.`,
+    description: `Manage registry authentication tokens in the vlt keychain.
+
+                  Target a specific configured registry by alias with
+                  \`vlt registry <alias> token <subcommand>\`.`,
     subcommands: {
         list: {
             usage: '',
@@ -131,15 +136,16 @@ const listTokens = async (rc, registry, identity, alias) => {
     }
 };
 export const command = async (conf) => {
-    const reg = normalizeRegistryKey(conf.options.registry);
+    const reg = normalizeRegistryKey(requireRegistry(conf));
     switch (conf.positionals[0]) {
+        case 'ls':
         case 'list': {
             const rc = new RegistryClient(conf.options);
             const identity = conf.options.identity;
             const registries = [];
             const seen = new Set();
             // Always query the default registry first
-            const defaultReg = conf.options.registry;
+            const defaultReg = requireRegistry(conf);
             seen.add(normalizeRegistryKey(defaultReg));
             registries.push(await listTokens(rc, defaultReg, identity, 'default'));
             // Then query all configured registry aliases
@@ -171,6 +177,7 @@ export const command = async (conf) => {
             await setToken(reg, `Bearer ${await readPassword('Paste bearer token: ')}`, conf.options.identity);
             break;
         }
+        case 'remove':
         case 'rm': {
             await deleteToken(reg, conf.options.identity);
             break;
@@ -178,7 +185,7 @@ export const command = async (conf) => {
         default: {
             throw error('Invalid token subcommand', {
                 found: conf.positionals[0],
-                validOptions: ['list', 'add', 'rm'],
+                validOptions: ['list', 'ls', 'add', 'rm', 'remove'],
                 code: 'EUSAGE',
             });
         }

package/dist/commands/uninstall.d.ts

@@ -7,6 +7,7 @@ export type UninstallResult = {
      */
     graph: Graph;
 };
+export declare const needsRegistry = true;
 export declare const usage: CommandUsage;
 export declare const views: {
     readonly json: (i: UninstallResult) => import("@vltpkg/graph").LockfileData;

package/dist/commands/uninstall.js

@@ -2,6 +2,7 @@ import { uninstall } from '@vltpkg/graph';
 import { commandUsage } from "../config/usage.js";
 import { parseRemoveArgs } from "../parse-add-remove-args.js";
 import { InstallReporter } from "./install/reporter.js";
+export const needsRegistry = true;
 export const usage = () => commandUsage({
     command: 'uninstall',
     usage: '[package ...]',

package/dist/commands/unpublish.d.ts

@@ -1,4 +1,5 @@
 import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const needsRegistry = true;
 export declare const usage: CommandUsage;
 export type CommandResult = {
     /** The package name */

package/dist/commands/unpublish.js

@@ -3,6 +3,8 @@ import { RegistryClient } from '@vltpkg/registry-client';
 import { Spec } from '@vltpkg/spec';
 import { asError } from '@vltpkg/types';
 import { commandUsage } from "../config/usage.js";
+import { resolveRegistry } from "../require-registry.js";
+export const needsRegistry = true;
 export const usage = () => commandUsage({
     command: 'unpublish',
     usage: ['<package>@<version>', '<package> --force'],
@@ -49,7 +51,8 @@ export const command = async (conf) => {
     if (!specArg) {
         throw error('unpublish requires a package spec argument (e.g. pkg@version)', { code: 'EUSAGE' });
     }
-    const { registry, otp, force } = conf.options;
+    const { otp, force } = conf.options;
+    const registry = await resolveRegistry(conf);
     const registryUrl = new URL(registry);
     const spec = Spec.parseArgs(specArg, conf.options);
     const name = spec.name;

package/dist/commands/update.d.ts

@@ -1,6 +1,7 @@
 import type { CommandFn, CommandUsage } from '../index.ts';
 import { InstallReporter } from './install/reporter.ts';
 import type { InstallResult } from './install.ts';
+export declare const needsRegistry = true;
 export declare const usage: CommandUsage;
 export declare const views: {
     readonly json: (i: InstallResult) => {

package/dist/commands/update.js

@@ -2,6 +2,7 @@ import { update } from '@vltpkg/graph';
 import { error } from '@vltpkg/error-cause';
 import { commandUsage } from "../config/usage.js";
 import { InstallReporter } from "./install/reporter.js";
+export const needsRegistry = true;
 export const usage = () => commandUsage({
     command: 'update',
     usage: '',

package/dist/commands/view.d.ts

@@ -2,6 +2,7 @@ import type { Manifest, Packument } from '@vltpkg/types';
 import type { PackageReportData } from '@vltpkg/security-archive';
 import type { CommandFn, CommandUsage } from '../index.ts';
 import type { ViewOptions } from '../view.ts';
+export declare const needsRegistry = true;
 export declare const usage: CommandUsage;
 export type ViewResult = {
     /** The full packument data from the registry */

package/dist/commands/view.js

@@ -5,6 +5,7 @@ import { SecurityArchive } from '@vltpkg/security-archive';
 import { Spec } from '@vltpkg/spec';
 import { joinDepIDTuple } from '@vltpkg/dep-id';
 import { commandUsage } from "../config/usage.js";
+export const needsRegistry = true;
 export const usage = () => commandUsage({
     command: 'view',
     usage: [
@@ -298,9 +299,9 @@ export const command = async (conf) => {
     const fieldPath = conf.positionals[1];
     const spec = Spec.parseArgs(specArg, conf.options);
     const pic = new PackageInfoClient(conf.options);
-    // Fetch the packument and resolved manifest
+    // Fetch the full packument (needs time, maintainers) and resolved manifest
     const [packument, resolvedManifest] = await Promise.all([
-        pic.packument(spec),
+        pic.packument(spec, { fullPackument: true }),
         pic.manifest(spec),
     ]);
     const manifest = resolvedManifest;

package/dist/commands/whoami.d.ts

@@ -1,5 +1,6 @@
 import type { JSONField } from '@vltpkg/types';
 import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const needsRegistry = true;
 export declare const usage: CommandUsage;
 type CommandResult = {
     username?: JSONField;

package/dist/commands/whoami.js

@@ -1,10 +1,15 @@
 import { RegistryClient } from '@vltpkg/registry-client';
 import { commandUsage } from "../config/usage.js";
+import { resolveRegistry } from "../require-registry.js";
+export const needsRegistry = true;
 export const usage = () => commandUsage({
     command: 'whoami',
     usage: [''],
     description: `Look up the username for the currently active token,
-                  when logged into a registry.`,
+                  when logged into a registry.
+
+                  Target a specific configured registry by alias with
+                  \`vlt registry <alias> whoami\`.`,
     options: {
         registry: {
             value: '<url>',
@@ -22,7 +27,7 @@ export const views = {
 };
 export const command = async (conf) => {
     const rc = new RegistryClient(conf.options);
-    const response = await rc.request(new URL('-/whoami', conf.options.registry), { useCache: false });
+    const response = await rc.request(new URL('-/whoami', await resolveRegistry(conf)), { useCache: false });
     const { username } = response.json();
     return { username };
 };

package/dist/config/definition.d.ts

@@ -21,9 +21,11 @@ export declare const commands: {
     readonly '?': "help";
     readonly info: "view";
     readonly ls: "list";
+    readonly out: "outdated";
     readonly show: "view";
     readonly xc: "exec-cache";
     readonly access: "access";
+    readonly audit: "audit";
     readonly bugs: "bugs";
     readonly build: "build";
     readonly cache: "cache";
@@ -35,21 +37,25 @@ export declare const commands: {
     readonly docs: "docs";
     readonly exec: "exec";
     readonly 'exec-local': "exec-local";
+    readonly fund: "fund";
     readonly help: "help";
     readonly init: "init";
     readonly install: "install";
     readonly login: "login";
     readonly logout: "logout";
     readonly list: "list";
+    readonly outdated: "outdated";
     readonly pack: "pack";
     readonly ping: "ping";
     readonly pkg: "pkg";
     readonly profile: "profile";
     readonly publish: "publish";
     readonly query: "query";
+    readonly registry: "registry";
     readonly repo: "repo";
     readonly 'run-exec': "run-exec";
     readonly run: "run";
+    readonly setup: "setup";
     readonly token: "token";
     readonly uninstall: "uninstall";
     readonly unpublish: "unpublish";
@@ -85,12 +91,17 @@ export declare const definition: import("jackspeak").Jack<{
     'no-color': import("jackspeak").ConfigOption<"boolean", false, undefined>;
 } & {
     registry: {
+        hint: string;
+        description: string;
+    };
+    'default-registry-alias': {
         hint: string;
         default: string;
         description: string;
     };
 } & {
     registry: import("jackspeak").ConfigOption<"string", false, readonly string[] | undefined>;
+    'default-registry-alias': import("jackspeak").ConfigOption<"string", false, readonly string[] | undefined>;
 } & {
     registries: {
         hint: string;
@@ -306,6 +317,21 @@ export declare const definition: import("jackspeak").Jack<{
     };
 } & {
     view: import("jackspeak").ConfigOption<"string", false, readonly string[] | undefined>;
+} & {
+    loglevel: {
+        hint: string;
+        default: string;
+        description: string;
+        validOptions: readonly ["silent", "error", "warn", "info", "verbose", "debug"];
+    };
+} & {
+    loglevel: import("jackspeak").ConfigOption<"string", false, readonly string[] | undefined>;
+} & {
+    verbose: {
+        description: string;
+    };
+} & {
+    verbose: import("jackspeak").ConfigOption<"boolean", false, undefined>;
 } & {
     'dashboard-root': {
         hint: string;
@@ -318,6 +344,10 @@ export declare const definition: import("jackspeak").Jack<{
         short: string;
         description: string;
     };
+    'save-exact': {
+        short: string;
+        description: string;
+    };
     'save-optional': {
         short: string;
         description: string;
@@ -331,9 +361,17 @@ export declare const definition: import("jackspeak").Jack<{
     };
 } & {
     'save-dev': import("jackspeak").ConfigOption<"boolean", false, undefined>;
+    'save-exact': import("jackspeak").ConfigOption<"boolean", false, undefined>;
     'save-optional': import("jackspeak").ConfigOption<"boolean", false, undefined>;
     'save-peer': import("jackspeak").ConfigOption<"boolean", false, undefined>;
     'save-prod': import("jackspeak").ConfigOption<"boolean", false, undefined>;
+} & {
+    'save-prefix': {
+        description: string;
+        default: string;
+    };
+} & {
+    'save-prefix': import("jackspeak").ConfigOption<"string", false, readonly string[] | undefined>;
 } & {
     'expect-results': {
         hint: string;

package/dist/config/definition.js

@@ -16,6 +16,7 @@ export const defaultEditor = () => process.env.EDITOR ||
         : 'vi');
 const canonicalCommands = {
     access: 'access',
+    audit: 'audit',
     bugs: 'bugs',
     build: 'build',
     cache: 'cache',
@@ -27,6 +28,7 @@ const canonicalCommands = {
     docs: 'docs',
     exec: 'exec',
     'exec-local': 'exec-local',
+    fund: 'fund',
     help: 'help',
     init: 'init',
     install: 'install',
@@ -34,15 +36,18 @@ const canonicalCommands = {
     logout: 'logout',
     list: 'list',
     ls: 'ls',
+    outdated: 'outdated',
     pack: 'pack',
     ping: 'ping',
     pkg: 'pkg',
     profile: 'profile',
     publish: 'publish',
     query: 'query',
+    registry: 'registry',
     repo: 'repo',
     'run-exec': 'run-exec',
     run: 'run',
+    setup: 'setup',
     token: 'token',
     uninstall: 'uninstall',
     unpublish: 'unpublish',
@@ -70,6 +75,7 @@ const aliases = {
     '?': 'help',
     info: 'view',
     ls: 'list',
+    out: 'outdated',
     show: 'view',
     xc: 'exec-cache',
 };
@@ -155,26 +161,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 +208,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 +581,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 +630,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 +652,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');