@vltpkg/cli-sdk 1.0.0-rc.9 → 1.0.1

package/dist/{esm/config → config}/definition.js

@@ -15,11 +15,15 @@ export const defaultEditor = () => process.env.EDITOR ||
         `${process.env.SYSTEMROOT}\\notepad.exe`
         : 'vi');
 const canonicalCommands = {
+    access: 'access',
     bugs: 'bugs',
     build: 'build',
     cache: 'cache',
     ci: 'ci',
     config: 'config',
+    create: 'create',
+    deprecate: 'deprecate',
+    'dist-tag': 'dist-tag',
     docs: 'docs',
     exec: 'exec',
     'exec-local': 'exec-local',
@@ -31,17 +35,23 @@ const canonicalCommands = {
     list: 'list',
     ls: 'ls',
     pack: 'pack',
+    ping: 'ping',
     pkg: 'pkg',
+    profile: 'profile',
     publish: 'publish',
     query: 'query',
+    registry: 'registry',
+    repo: 'repo',
     'run-exec': 'run-exec',
     run: 'run',
-    serve: 'serve',
+    setup: 'setup',
     token: 'token',
     uninstall: 'uninstall',
+    unpublish: 'unpublish',
     update: 'update',
     'exec-cache': 'exec-cache',
     version: 'version',
+    view: 'view',
     whoami: 'whoami',
 };
 const aliases = {
@@ -56,12 +66,13 @@ const aliases = {
     r: 'run',
     'run-script': 'run',
     rx: 'run-exec',
-    s: 'serve',
     x: 'exec',
     xl: 'exec-local',
     h: 'help',
     '?': 'help',
+    info: 'view',
     ls: 'list',
+    show: 'view',
     xc: 'exec-cache',
 };
 /**
@@ -94,34 +105,21 @@ export const recordFields = [
     'git-hosts',
     'registries',
     'git-host-archives',
-    'scope-registries',
+    'scoped-registries',
     'jsr-registries',
 ];
 export const isRecordField = (s) => recordFields.includes(s);
-const stopParsingCommands = [
-    'run',
-    'run-exec',
-    'exec-local',
-    'exec',
-];
-let stopParsing = undefined;
 const j = jack({
     envPrefix: 'VLT',
     allowPositionals: true,
     usage: `vlt [<options>] [<cmd> [<args> ...]]`,
-    stopAtPositionalTest: arg => {
-        if (stopParsing)
-            return true;
-        const a = arg;
-        // we stop parsing AFTER the thing, so you can do
-        // vlt run --vlt --configs scriptName --args --for --script
-        // or
-        // vlt exec --vlt --configs command --args --for --command
-        if (stopParsingCommands.includes(commands[a])) {
-            stopParsing = true;
-        }
-        return false;
-    },
+    // vlt options can appear on either side of the command/script
+    // name. To forward an argument (especially a flag-like one) to
+    // the underlying bin/script without vlt interpreting it, place
+    // it after a `--` terminator, e.g.:
+    //   vlt run scriptName --vlt-flag -- --script-flag --more
+    // Node's `parseArgs` natively treats everything following `--`
+    // as positional, so no special-casing is needed here.
 })
     .heading('vlt')
     .description(`More documentation available at <https://docs.vlt.sh>`)
@@ -159,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:
 
@@ -186,17 +204,18 @@ 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.
                     `,
     },
-    'scope-registries': {
+    'scoped-registries': {
         hint: '@scope=url',
         description: `Map package name scopes to registry URLs.
 
                     For example,
-                    \`--scope-registries @acme=https://registry.acme/\`
+                    \`--scoped-registries @acme=https://registry.acme/\`
                     would tell vlt to fetch any packages named
                     \`@acme/...\` from the \`https://registry.acme/\`
                     registry.
@@ -289,6 +308,11 @@ export const definition = j
                     packages based on their \`cpu\` value.`,
         default: process.arch,
     },
+    libc: {
+        description: `Override the libc family to use as the selector when choosing
+                    packages based on their \`libc\` value (e.g. glibc, musl).
+                    By default, this is auto-detected on Linux systems.`,
+    },
     'node-version': {
         hint: 'version',
         description: `Node version to use when choosing packages based on
@@ -381,7 +405,6 @@ export const definition = j
                     supported.`,
     },
     'workspace-group': {
-        short: 'g',
         description: `Specify named workspace group names to load and operate on
                     when doing recursive operations on workspaces.`,
     },
@@ -493,6 +516,28 @@ export const definition = j
                     vlt will interpret the first argument as the package, and
                     attempt to run the default executable.`,
     },
+})
+    .opt({
+    call: {
+        hint: 'cmd',
+        description: `When running \`vlt exec\`, provide an arbitrary command
+                    string to execute after installing and adding any specified
+                    package bins to the PATH.
+
+                    If a package is specified (via positionals or
+                    \`--package\`), it will be installed and its executables
+                    added to the PATH before the \`--call\` command runs.
+
+                    The command string is executed via the configured
+                    \`script-shell\`, or the \`SHELL\` environment variable,
+                    falling back to \`/bin/sh\` on Unix or \`cmd.exe\` on
+                    Windows. On Unix, the shell is invoked with \`-c\`; on
+                    Windows with \`/c\`.
+
+                    Example:
+                    \`vlt exec create-react-app --call="echo $PWD"\`
+                    \`vlt exec --call="echo $PWD" --scope=":workspace"\``,
+    },
 })
     .opt({
     view: {
@@ -507,11 +552,14 @@ export const definition = j
                       consumption.
                     - json: Parseable JSON output for machines.
                     - inspect: Output results with \`util.inspect\`.
-                    - gui: Start a local web server and opens a browser to
-                      explore the results. (Only relevant for certain
-                      commands.)
                     - mermaid: Output mermaid diagramming syntax. (Only
                       relevant for certain commands.)
+                    - svg: Render the dependency graph as an SVG image and
+                      open it. (Only relevant for certain commands.)
+                    - png: Render the dependency graph as a PNG image and
+                      open it. (Only relevant for certain commands.)
+                    - count: Output the number of dependency relationships in
+                      the result set.
                     - silent: Suppress all output to stdout.
 
                     If the requested view format is not supported for the
@@ -522,11 +570,48 @@ export const definition = j
             'human',
             'json',
             'mermaid',
-            'gui',
+            'svg',
+            'png',
+            'count',
             'inspect',
             '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': {
@@ -541,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
@@ -557,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': {
@@ -576,6 +676,10 @@ export const definition = j
     'dry-run': {
         description: 'Run command without making any changes',
     },
+    force: {
+        short: 'f',
+        description: 'Force potentially dangerous operations, such as unpublishing an entire package.',
+    },
     'expect-lockfile': {
         description: 'Fail if lockfile is missing or out of date. Used by ci command to enforce lockfile integrity.',
     },
@@ -603,7 +707,6 @@ export const definition = j
     access: {
         description: 'Set the access level of the package',
         validOptions: ['public', 'restricted'],
-        default: 'public',
     },
 })
     .opt({
@@ -615,13 +718,18 @@ export const definition = j
         description: `Directory to use for pack and publish operations instead of the current directory.
                     The directory must exist and nothing will be copied to it.`,
     },
-    port: {
-        hint: 'number',
-        description: `Port for the browser-based UI server when using vlt serve command (default: 8000).`,
-    },
-    'registry-port': {
-        hint: 'number',
-        description: `Port for the VSR registry when using vlt serve command (default: 1337).`,
+})
+    .flag({
+    telemetry: {
+        description: `Enable anonymous usage telemetry.
+
+                    vlt collects anonymized usage data to help improve
+                    the tool. No personally identifiable information is
+                    ever sent.
+
+                    Set \`--no-telemetry\` or \`VLT_TELEMETRY=0\` or
+                    \`DO_NOT_TRACK=1\` to opt out.`,
+        default: true,
     },
 })
     .flag({
@@ -655,4 +763,3 @@ export const getSortedCliOptions = () => {
     });
 };
 export const getSortedKeys = () => Object.keys(definition.toJSON()).sort((a, b) => a.localeCompare(b));
-//# sourceMappingURL=definition.js.map

package/dist/{esm/config → config}/index.d.ts

@@ -216,4 +216,3 @@ export type ParsedConfig = Config & {
  * A fully loaded {@link Config} object
  */
 export type LoadedConfig = ParsedConfig;
-//# sourceMappingURL=index.d.ts.map

package/dist/{esm/config → config}/index.js

@@ -24,6 +24,7 @@ import { error } from '@vltpkg/error-cause';
 import { PackageInfoClient } from '@vltpkg/package-info';
 import { PackageJson } from '@vltpkg/package-json';
 import { resetCaches } from '@vltpkg/dep-id';
+import { getOptions } from '@vltpkg/spec';
 import { assertRecordStringString, assertRecordStringT, isRecordStringString, } from '@vltpkg/types';
 import { find, load, reload, save } from '@vltpkg/vlt-json';
 import { Monorepo } from '@vltpkg/workspaces';
@@ -128,6 +129,10 @@ export class Config {
             catalogs: load('catalogs', o => assertRecordStringT(o, isRecordStringString, 'Record<string, Record<string, string>>')),
         };
         const options = Object.assign(asRecords, extras);
+        // Ensure spec-related options (registries, jsr-registries, git hosts, etc.)
+        // are always filled with defaults. Some downstream libraries (eg. @vltpkg/dep-id)
+        // expect these defaults to be present even when the user didn't configure them.
+        Object.assign(options, getOptions(options));
         this.#options = Object.assign(options, {
             packageInfo: new PackageInfoClient(options),
             [kCustomInspect]() {
@@ -207,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');
@@ -226,6 +237,7 @@ export class Config {
      * If the config value is not set at all, an empty object is returned.
      */
     getRecord(k) {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
         const pairs = this.get(k);
         if (!pairs)
             return {};
@@ -281,10 +293,40 @@ export class Config {
             });
         }
         const { command, ...values } = recordsToPairs(c);
+        // Validate registries keys don't contain reserved ~ character
+        const registries = c.registries;
+        if (registries && typeof registries === 'object') {
+            const registriesObj = Array.isArray(registries) ?
+                reducePairs(registries)
+                : registries;
+            for (const key of Object.keys(registriesObj)) {
+                if (key === '' || key.includes('~')) {
+                    throw error('Reserved character found in registries name', {
+                        path: file,
+                        found: key,
+                    });
+                }
+            }
+        }
         if (command) {
             for (const [c, opts] of Object.entries(command)) {
                 const cmd = getCommand(c);
-                if (cmd) {
+                if (cmd && opts && typeof opts === 'object') {
+                    // Validate registries in command-specific config
+                    const cmdRegistries = opts.registries;
+                    if (cmdRegistries && typeof cmdRegistries === 'object') {
+                        const cmdRegistriesObj = Array.isArray(cmdRegistries) ?
+                            reducePairs(cmdRegistries)
+                            : cmdRegistries;
+                        for (const key of Object.keys(cmdRegistriesObj)) {
+                            if (key === '' || key.includes('~')) {
+                                throw error('Reserved character found in registries name', {
+                                    path: file,
+                                    found: key,
+                                });
+                            }
+                        }
+                    }
                     this.commandValues[cmd] = merge(this.commandValues[cmd] ?? {}, opts);
                 }
             }
@@ -451,4 +493,3 @@ export class Config {
     }
 }
 const isParsed = (c) => !!(c.values && c.positionals && c.command);
-//# sourceMappingURL=index.js.map

package/dist/{esm/config → config}/merge.d.ts

@@ -1,4 +1,3 @@
 type MergeableObject = Record<string, unknown>;
 export declare const merge: <T extends MergeableObject>(base: T, add: T) => T;
 export {};
-//# sourceMappingURL=merge.d.ts.map

package/dist/{esm/config → config}/merge.js

@@ -25,4 +25,3 @@ export const merge = (base, add) => Object.fromEntries(Object.entries(base)
     .concat(
 // already merged together if existing, so just get new additions
 Object.entries(add).filter(([k]) => base[k] === undefined)));
-//# sourceMappingURL=merge.js.map

package/dist/{esm/config → config}/usage.d.ts

@@ -16,4 +16,3 @@ export type CommandUsageDefinition = {
     }>;
 };
 export declare const commandUsage: ({ command, usage, description, subcommands, examples, options, }: CommandUsageDefinition) => ReturnType<CommandUsage>;
-//# sourceMappingURL=usage.d.ts.map

package/dist/{esm/config → config}/usage.js

@@ -37,4 +37,3 @@ export const commandUsage = ({ command, usage, description, subcommands, example
     }
     return j;
 };
-//# sourceMappingURL=usage.js.map

package/dist/{esm/custom-help.d.ts → custom-help.d.ts}

@@ -6,4 +6,3 @@ export declare const generateDefaultHelp: (colors?: boolean) => string;
  * Generates the full help output with all commands when --all flag is used
  */
 export declare const generateFullHelp: (colors?: boolean) => string;
-//# sourceMappingURL=custom-help.d.ts.map