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

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

@@ -15,10 +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',
@@ -30,17 +35,21 @@ const canonicalCommands = {
     list: 'list',
     ls: 'ls',
     pack: 'pack',
+    ping: 'ping',
     pkg: 'pkg',
+    profile: 'profile',
     publish: 'publish',
     query: 'query',
+    repo: 'repo',
     'run-exec': 'run-exec',
     run: 'run',
-    serve: 'serve',
     token: 'token',
     uninstall: 'uninstall',
+    unpublish: 'unpublish',
     update: 'update',
     'exec-cache': 'exec-cache',
     version: 'version',
+    view: 'view',
     whoami: 'whoami',
 };
 const aliases = {
@@ -55,12 +64,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',
 };
 /**
@@ -93,34 +103,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>`)
@@ -190,12 +187,12 @@ export const definition = j
                     mapping in most cases.
                     `,
     },
-    '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.
@@ -288,6 +285,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
@@ -380,7 +382,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.`,
     },
@@ -492,6 +493,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: {
@@ -506,11 +529,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
@@ -521,7 +547,9 @@ export const definition = j
             'human',
             'json',
             'mermaid',
-            'gui',
+            'svg',
+            'png',
+            'count',
             'inspect',
             'silent',
         ],
@@ -575,6 +603,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.',
     },
@@ -602,7 +634,6 @@ export const definition = j
     access: {
         description: 'Set the access level of the package',
         validOptions: ['public', 'restricted'],
-        default: 'public',
     },
 })
     .opt({
@@ -614,13 +645,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({
@@ -654,4 +690,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]() {
@@ -226,6 +231,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 +287,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 +487,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

package/dist/{esm/custom-help.js → custom-help.js}

@@ -44,6 +44,13 @@ const makeStyler = (colors) => {
 };
 // Single source of truth for all commands with metadata
 const allCommands = [
+    {
+        name: 'bugs',
+        aliases: [],
+        args: '[<spec>]',
+        desc: 'Open the bug tracker for a package',
+        showByDefault: false,
+    },
     {
         name: 'build',
         aliases: ['b'],
@@ -73,6 +80,13 @@ const allCommands = [
         desc: 'Get or set configuration',
         showByDefault: false,
     },
+    {
+        name: 'create',
+        aliases: [],
+        args: '<initializer> [args...]',
+        desc: 'Create a new project from a template',
+        showByDefault: false,
+    },
     {
         name: 'docs',
         aliases: [],
@@ -153,6 +167,13 @@ const allCommands = [
         desc: 'Create a tarball from a package',
         showByDefault: false,
     },
+    {
+        name: 'ping',
+        aliases: [],
+        args: '[<registry-alias>]',
+        desc: 'Ping configured registries',
+        showByDefault: false,
+    },
     {
         name: 'pkg',
         aliases: ['p'],
@@ -177,6 +198,13 @@ const allCommands = [
         showByDefault: true,
         defaultOrder: 3,
     },
+    {
+        name: 'repo',
+        aliases: [],
+        args: '[<spec>]',
+        desc: 'Open the repository page for a package',
+        showByDefault: false,
+    },
     {
         name: 'run',
         aliases: ['r'],
@@ -192,14 +220,6 @@ const allCommands = [
         desc: 'Run a script &/or fallback to executing a binary',
         showByDefault: false,
     },
-    {
-        name: 'serve',
-        aliases: ['s'],
-        args: '',
-        desc: 'Start a local package registry server',
-        showByDefault: true,
-        defaultOrder: 9,
-    },
     {
         name: 'token',
         aliases: [],
@@ -214,6 +234,13 @@ const allCommands = [
         desc: 'Remove dependencies',
         showByDefault: false,
     },
+    {
+        name: 'unpublish',
+        aliases: [],
+        args: '<pkg>[@<version>]',
+        desc: 'Remove a package from the registry',
+        showByDefault: false,
+    },
     {
         name: 'update',
         aliases: ['u'],
@@ -397,4 +424,3 @@ Get support: https://${s('bold', 'vlt.community')}
 
 ${s('dim', `Run \`vlt help <command>\` for detailed information about a specific command.`)}`;
 };
-//# sourceMappingURL=custom-help.js.map

package/dist/{esm/exec-command.d.ts → exec-command.d.ts}

@@ -50,4 +50,3 @@ export declare class ExecCommand<B extends RunnerBG, F extends RunnerFG> {
     }[];
 }
 export {};
-//# sourceMappingURL=exec-command.d.ts.map

package/dist/{esm/exec-command.js → exec-command.js}

@@ -5,6 +5,7 @@
 import { error } from '@vltpkg/error-cause';
 import { isErrorWithCause } from '@vltpkg/types';
 import { Query } from '@vltpkg/query';
+import { createDiffFilesProvider } from "./query-diff-files.js";
 import { actual } from '@vltpkg/graph';
 import { isRunResult } from '@vltpkg/run';
 import { Monorepo } from '@vltpkg/workspaces';
@@ -72,11 +73,11 @@ export class ExecCommand {
         this.conf = conf;
         this.bg = bg;
         this.fg = fg;
-        this.view = this.validViewValues.get(conf.values.view) ?? 'human';
         const { projectRoot, positionals: [arg0, ...args], } = conf;
         this.arg0 = arg0;
         this.args = args;
         this.projectRoot = projectRoot;
+        this.view = this.validViewValues.get(conf.values.view) ?? 'human';
     }
     #targetCount() {
         if (this.#nodes)
@@ -114,6 +115,7 @@ export class ExecCommand {
                 /* c8 ignore stop */
                 securityArchive: undefined,
                 hostContexts,
+                diffFiles: createDiffFilesProvider(this.projectRoot),
             });
             const { nodes } = await query.search(queryString, {
                 signal: new AbortController().signal,
@@ -195,10 +197,6 @@ export class ExecCommand {
         }
         const results = {};
         for (const [path, result] of resultMap) {
-            if (result.status === 0 && result.signal === null) {
-                result.stdout = '';
-                result.stderr = '';
-            }
             results[path] = result;
         }
         return results;
@@ -208,6 +206,12 @@ export class ExecCommand {
         if (this.view !== 'human')
             return;
         if (result.status === 0 && result.signal === null) {
+            /* c8 ignore start */
+            if (result.stderr)
+                stderr(ansiToAnsi(result.stderr));
+            if (result.stdout)
+                stdout(ansiToAnsi(result.stdout));
+            /* c8 ignore stop */
             stdout(path, 'ok');
         }
         else {
@@ -241,8 +245,10 @@ export class ExecCommand {
             assert(first, error('no nodes found'));
             return resolve(this.projectRoot, first);
         }
-        return (this.#monorepo?.values().next().value?.fullpath ??
-            this.projectRoot);
+        // When no workspace/monorepo targeting is specified, use the current
+        // working directory. This matches npx behavior and is required for
+        // tools like node-gyp that must run in the correct directory.
+        return (this.#monorepo?.values().next().value?.fullpath ?? process.cwd());
     }
     fgArg() {
         const cwd = this.getCwd();
@@ -255,6 +261,7 @@ export class ExecCommand {
             arg0,
             args: this.args,
             env: this.env,
+            ignoreMissing: this.conf.get('if-present') ?? this.#defaultIgnoreMissing,
             projectRoot: this.projectRoot,
             packageJson: this.conf.options.packageJson,
             'script-shell': this.arg0 ? this.conf.get('script-shell') : false,
@@ -305,4 +312,3 @@ export class ExecCommand {
         return targets;
     }
 }
-//# sourceMappingURL=exec-command.js.map

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

@@ -1,4 +1,3 @@
 export type { Command, CommandFn, CommandUsage, } from './load-command.ts';
 declare const run: () => Promise<void>;
 export default run;
-//# sourceMappingURL=index.d.ts.map

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

@@ -67,7 +67,6 @@ const run = async () => {
         return process.exit(process.exitCode || 1);
     }
     const command = await loadCommand(vlt.command);
-    await outputCommand(command, vlt, { start });
+    await outputCommand(command, vlt, { start, vltVersion: version });
 };
 export default run;
-//# sourceMappingURL=index.js.map

package/dist/{esm/load-command.d.ts → load-command.d.ts}

@@ -13,4 +13,3 @@ export type Command<T> = {
     views: Views<T>;
 };
 export declare const loadCommand: <T>(command: Commands[keyof Commands] | undefined) => Promise<Command<T>>;
-//# sourceMappingURL=load-command.d.ts.map

package/dist/{esm/load-command.js → load-command.js}

@@ -18,4 +18,3 @@ export const loadCommand = async (command) => {
         });
     }
 };
-//# sourceMappingURL=load-command.js.map

package/dist/mermaid-image-view.d.ts

@@ -0,0 +1,18 @@
+import { ViewClass } from './view.ts';
+import type { OutputFormat } from './render-mermaid.ts';
+import type { MermaidOutputGraph } from '@vltpkg/graph';
+/**
+ * A ViewClass that renders mermaid output as SVG or PNG
+ * (saved to a temp file and opened).
+ *
+ * Uses `beautiful-mermaid` for SVG rendering and
+ * `@resvg/resvg-wasm` for PNG conversion — no external
+ * process spawning.
+ */
+export declare class MermaidImageView extends ViewClass<MermaidOutputGraph> {
+    format: OutputFormat;
+    constructor(...args: ConstructorParameters<typeof ViewClass<MermaidOutputGraph>>);
+    done(result: MermaidOutputGraph, _opts: {
+        time: number;
+    }): Promise<void>;
+}

package/dist/mermaid-image-view.js

@@ -0,0 +1,36 @@
+import { mermaidOutput } from '@vltpkg/graph';
+import { urlOpen } from '@vltpkg/url-open';
+import { stderr } from "./output.js";
+import { ViewClass } from "./view.js";
+/**
+ * A ViewClass that renders mermaid output as SVG or PNG
+ * (saved to a temp file and opened).
+ *
+ * Uses `beautiful-mermaid` for SVG rendering and
+ * `@resvg/resvg-wasm` for PNG conversion — no external
+ * process spawning.
+ */
+export class MermaidImageView extends ViewClass {
+    format;
+    constructor(...args) {
+        super(...args);
+        this.format = this.config.values.view;
+    }
+    async done(result, _opts) {
+        const mermaidText = mermaidOutput(result);
+        // Dynamic import to avoid loading render-mermaid eagerly
+        const { renderMermaidToFile, renderMermaidToPng } = await import("./render-mermaid.js");
+        if (this.format === 'png') {
+            stderr(`Generating PNG image...`);
+            const filePath = await renderMermaidToPng(mermaidText);
+            stderr(`Image saved to: ${filePath}`);
+            await urlOpen(filePath);
+        }
+        else {
+            stderr(`Generating SVG image...`);
+            const filePath = await renderMermaidToFile(mermaidText);
+            stderr(`Image saved to: ${filePath}`);
+            await urlOpen(filePath);
+        }
+    }
+}

package/dist/{esm/output.d.ts → output.d.ts}

@@ -14,8 +14,8 @@ export type OnDone<T> = (result: T) => Promise<unknown>;
  * the user-requested view, or the default if the user requested a view
  * that is not defined for this command.
  */
-export declare const outputCommand: <T>(cliCommand: Command<T>, conf: LoadedConfig, { start }?: {
+export declare const outputCommand: <T>(cliCommand: Command<T>, conf: LoadedConfig, { start, vltVersion }?: {
     start: number;
+    vltVersion?: string;
 }) => Promise<void>;
 export {};
-//# sourceMappingURL=output.d.ts.map