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

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

@@ -1,5 +1,6 @@
 import { loadPackageJson } from 'package-json-from-dist';
 import chalk from 'chalk';
+import { commandAliases } from "./config/definition.js";
 const { version } = loadPackageJson(import.meta.filename, process.env.__VLT_INTERNAL_CLI_PACKAGE_JSON);
 // Custom yellow color: #FFE15D
 const customYellow = chalk.hex('#FFE15D');
@@ -42,200 +43,176 @@ const makeStyler = (colors) => {
         return styledText;
     };
 };
-// Single source of truth for all commands with metadata
-const allCommands = [
-    {
-        name: 'build',
-        aliases: ['b'],
+/**
+ * Help metadata for every command target in the command registry. Using a
+ * record keyed by CommandName makes missing or stale entries a type error;
+ * aliases are derived separately from the registry below.
+ */
+const commandHelp = {
+    access: {
+        args: '<command> [<args>]',
+        desc: 'Manage package access and team permissions',
+    },
+    bugs: {
+        args: '[<spec>]',
+        desc: 'Open the bug tracker for a package',
+    },
+    build: {
         args: '<selector>',
         desc: 'Build packages with lifecycle scripts',
-        showByDefault: true,
         defaultOrder: 4,
     },
-    {
-        name: 'cache',
-        aliases: [],
+    cache: {
         args: '[add|ls|info|clean|delete|delete-before|delete-all]',
         desc: 'Manage the package cache',
-        showByDefault: false,
     },
-    {
-        name: 'ci',
-        aliases: [],
+    ci: {
         args: '',
         desc: 'Clean install (frozen lockfile)',
-        showByDefault: false,
     },
-    {
-        name: 'config',
-        aliases: [],
+    config: {
         args: '[get|pick|list|set|delete|edit|location]',
         desc: 'Get or set configuration',
-        showByDefault: false,
     },
-    {
-        name: 'docs',
-        aliases: [],
+    create: {
+        args: '<initializer> [args...]',
+        desc: 'Create a new project from a template',
+    },
+    deprecate: {
+        args: '<pkg>[@<version>] <message>',
+        desc: 'Deprecate a package or version range',
+    },
+    'dist-tag': {
+        args: '[add|rm|ls] [<args>]',
+        desc: 'Manage package distribution tags',
+    },
+    docs: {
         args: '',
         desc: 'Open the docs of the current project',
-        showByDefault: false,
     },
-    {
-        name: 'exec',
-        aliases: ['x'],
+    exec: {
         args: '<executable>',
         desc: 'Execute a package bin',
-        showByDefault: true,
         defaultOrder: 6,
     },
-    {
-        name: 'exec-cache',
-        aliases: ['xc'],
+    'exec-cache': {
         args: '[ls|delete|info|install]',
         desc: 'Manage the exec cache',
-        showByDefault: false,
     },
-    {
-        name: 'exec-local',
-        aliases: ['xl'],
+    'exec-local': {
         args: '<command>',
         desc: 'Execute a local package bin',
-        showByDefault: false,
     },
-    {
-        name: 'help',
-        aliases: ['h', '?'],
+    help: {
         args: '[<command>]',
         desc: 'Show help for a command',
-        showByDefault: false,
     },
-    {
-        name: 'init',
-        aliases: [],
+    init: {
         args: '',
         desc: 'Initialize a new project',
-        showByDefault: true,
         defaultOrder: 1,
     },
-    {
-        name: 'install',
-        aliases: ['i', 'add'],
+    install: {
         args: '[<package>...]',
         desc: 'Install dependencies',
-        showByDefault: true,
         defaultOrder: 2,
     },
-    {
-        name: 'list',
-        aliases: ['ls'],
+    list: {
         args: '',
         desc: 'List installed packages',
-        showByDefault: false,
     },
-    {
-        name: 'login',
-        aliases: [],
+    login: {
         args: '',
         desc: 'Authenticate with a registry',
-        showByDefault: false,
     },
-    {
-        name: 'logout',
-        aliases: [],
+    logout: {
         args: '',
         desc: 'Log out from a registry',
-        showByDefault: false,
     },
-    {
-        name: 'pack',
-        aliases: [],
+    pack: {
         args: '',
         desc: 'Create a tarball from a package',
-        showByDefault: false,
     },
-    {
-        name: 'pkg',
-        aliases: ['p'],
+    ping: {
+        args: '[<registry-alias>]',
+        desc: 'Ping configured registries',
+    },
+    pkg: {
         args: '<command>',
         desc: 'Manage package metadata',
-        showByDefault: true,
         defaultOrder: 7,
     },
-    {
-        name: 'publish',
-        aliases: ['pub'],
+    profile: {
+        args: '<command> [<args>]',
+        desc: 'Get or set registry profile properties',
+    },
+    publish: {
         args: '',
         desc: 'Publish package to registry',
-        showByDefault: true,
         defaultOrder: 8,
     },
-    {
-        name: 'query',
-        aliases: ['q'],
+    query: {
         args: '<selector>',
         desc: 'Query for packages in the project',
-        showByDefault: true,
         defaultOrder: 3,
     },
-    {
-        name: 'run',
-        aliases: ['r'],
+    registry: {
+        args: '<alias> <command>',
+        desc: 'Run an account command against a named registry',
+        defaultOrder: 9,
+    },
+    repo: {
+        args: '[<spec>]',
+        desc: 'Open the repository page for a package',
+    },
+    run: {
         args: '<script>',
         desc: 'Run a script defined in package.json',
-        showByDefault: true,
         defaultOrder: 5,
     },
-    {
-        name: 'run-exec',
-        aliases: ['rx'],
+    'run-exec': {
         args: '<script>',
         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,
+    setup: {
+        args: '[<account>]',
+        desc: 'Configure your vlt.io account registries',
+        defaultOrder: 0,
     },
-    {
-        name: 'token',
-        aliases: [],
+    token: {
         args: '[add|rm]',
         desc: 'Manage authentication tokens',
-        showByDefault: false,
     },
-    {
-        name: 'uninstall',
-        aliases: ['rm'],
+    uninstall: {
         args: '[<package>...]',
         desc: 'Remove dependencies',
-        showByDefault: false,
     },
-    {
-        name: 'update',
-        aliases: ['u'],
+    unpublish: {
+        args: '<pkg>[@<version>]',
+        desc: 'Remove a package from the registry',
+    },
+    update: {
         args: '',
         desc: 'Update package versions to latest in-range',
-        showByDefault: false,
     },
-    {
-        name: 'version',
-        aliases: [],
+    version: {
         args: '<increment>',
         desc: 'Bump package version',
-        showByDefault: false,
     },
-    {
-        name: 'whoami',
-        aliases: [],
+    view: {
+        args: '<pkg>[@<version>] [<field>]',
+        desc: 'View registry information about a package',
+    },
+    whoami: {
         args: '',
         desc: 'Display the current user',
-        showByDefault: false,
     },
-];
+};
+const allCommands = Object.entries(commandHelp).map(([name, metadata]) => ({
+    name,
+    aliases: commandAliases.get(name) ?? [],
+    ...metadata,
+}));
 /**
  * Generates the custom default help output for vlt
  */
@@ -243,8 +220,8 @@ export const generateDefaultHelp = (colors = false) => {
     const s = makeStyler(colors);
     // Get default commands and sort by defaultOrder
     const defaultCommands = allCommands
-        .filter(cmd => cmd.showByDefault)
-        .sort((a, b) => (a.defaultOrder || 0) - (b.defaultOrder || 0));
+        .filter(cmd => cmd.defaultOrder !== undefined)
+        .sort((a, b) => (a.defaultOrder ?? 0) - (b.defaultOrder ?? 0));
     // Generate commands with tighter alias spacing but proper table structure
     const commandsSection = defaultCommands
         .map(cmd => {
@@ -255,7 +232,7 @@ export const generateDefaultHelp = (colors = false) => {
         const nameColumn = cmd.name.padEnd(10);
         // Consistent args column (14 chars)
         const argsColumn = cmd.args.padEnd(16);
-        return `  ${s('dim', aliasColumn)}${s(['yellow', 'bold'], nameColumn)}${s('dim', argsColumn)}${cmd.desc}`;
+        return `  ${s('dim', aliasColumn)}${s(['yellow', 'bold'], nameColumn)}${s('dim', argsColumn)} ${cmd.desc}`;
     })
         .join('\n');
     return `${s(['bold'], '⚡️ vlt')} ${s('dim', '/vōlt/')} next-gen package management ${s('dim', `v${version}`)}
@@ -291,6 +268,8 @@ export const generateFullHelp = (colors = false) => {
     const s = makeStyler(colors);
     // Use all commands sorted alphabetically
     const commands = [...allCommands].sort((a, b) => a.name.localeCompare(b.name));
+    const aliasLabels = commands.map(cmd => cmd.aliases.length ? `${cmd.aliases.join(', ')},` : '');
+    const aliasWidth = Math.max(...aliasLabels.map(label => label.length));
     // Define only globally applicable flags (alphabetically sorted by long name)
     const flags = [
         {
@@ -321,7 +300,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'],
@@ -345,17 +324,14 @@ export const generateFullHelp = (colors = false) => {
         if (firstLetter !== lastFirstLetter && index > 0) {
             commandsSection += '\n';
         }
-        // Fixed width columns for proper alignment with space after comma
-        const aliasColumn = cmd.aliases.length > 0 ?
-            (cmd.aliases.join(', ') + ', ').padEnd(9)
-            : '         ';
+        const aliasColumn = aliasLabels[index]?.padEnd(aliasWidth) ?? '';
         const nameColumn = cmd.name.padEnd(12);
         // Truncate args if longer than 16 chars and add ellipsis
         const truncatedArgs = cmd.args.length > 16 ?
             cmd.args.substring(0, 13) + '...'
             : cmd.args;
         const argsColumn = truncatedArgs.padEnd(16);
-        commandsSection += `${s('dim', aliasColumn)}${s(['yellow', 'bold'], nameColumn)}${s('dim', argsColumn)}${cmd.desc}`;
+        commandsSection += `  ${s('dim', aliasColumn)} ${s(['yellow', 'bold'], nameColumn)} ${s('dim', argsColumn)} ${cmd.desc}`;
         if (index < commands.length - 1) {
             commandsSection += '\n';
         }
@@ -397,4 +373,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}

@@ -66,8 +66,11 @@ 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 });
+    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}

@@ -11,6 +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>>;
-//# 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

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

@@ -2,8 +2,20 @@ 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 ||
+    process.env.GITLAB_CI ||
+    process.env.CIRCLECI ||
+    process.env.JENKINS_URL ||
+    process.env.BUILDKITE ||
+    process.env.TRAVIS);
+/* c8 ignore stop */
 const supportsColor = (stream) => {
     const res = createSupportsColor(stream, { sniffFlags: false });
     if (res === false)
@@ -77,8 +89,10 @@ const startView = (conf, opts, views, { start } = { start: Date.now() }) => {
  * the user-requested view, or the default if the user requested a view
  * that is not defined for this command.
  */
-export const outputCommand = async (cliCommand, conf, { start } = { start: Date.now() }) => {
-    const { usage, views, command } = cliCommand;
+export const outputCommand = async (cliCommand, conf, { start, vltVersion } = {
+    start: Date.now(),
+}) => {
+    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) {
@@ -99,11 +113,35 @@ export const outputCommand = async (cliCommand, conf, { start } = { start: Date.
     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,
+            duration_ms,
+            success: true,
+            node_version: process.version,
+            vlt_version: vltVersion ?? 'unknown',
+            os: process.platform,
+            arch: process.arch,
+            ci: isCI(),
+        }, telemetryEnabled);
         if (output !== undefined && conf.values.view !== 'silent') {
             stdout(conf.values.view === 'json' ?
                 JSON.stringify(output, null, 2)
@@ -112,10 +150,40 @@ export const outputCommand = async (cliCommand, conf, { start } = { start: Date.
                     colors: stdoutColor,
                 }, output));
         }
+        // Await the flush so pending telemetry events are sent before
+        // the process exits.  The flush has a built-in timeout cap
+        // (SHUTDOWN_TIMEOUT_MS) so it will never block for long, and the
+        // timer is unreffed so even if this is not awaited the process
+        // can still exit promptly.
+        await flushTelemetry();
     }
     catch (err) {
+        stopRequestLog();
         onError?.(err);
         process.exitCode ||= 1;
+        const duration_ms = Date.now() - start;
+        trackCommand({
+            command: commandName,
+            duration_ms,
+            success: false,
+            node_version: process.version,
+            vlt_version: vltVersion ?? 'unknown',
+            os: process.platform,
+            arch: process.arch,
+            ci: isCI(),
+        }, telemetryEnabled);
+        const errorCode = (err instanceof Error &&
+            err.cause &&
+            typeof err.cause === 'object' &&
+            'code' in err.cause &&
+            typeof err.cause.code === 'string') ?
+            err.cause.code
+            : undefined;
+        trackError({
+            command: commandName,
+            error_code: errorCode,
+        }, telemetryEnabled);
+        await flushTelemetry();
         printErr(err, usage, stderr, {
             ...formatOptions,
             colors: stderrColor,
@@ -123,4 +191,3 @@ export const outputCommand = async (cliCommand, conf, { start } = { start: Date.
         process.exit(process.exitCode);
     }
 };
-//# sourceMappingURL=output.js.map