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

package/dist/{esm/commands → commands}/install.d.ts

@@ -1,6 +1,6 @@
 import { InstallReporter } from './install/reporter.ts';
 import type { DepID } from '@vltpkg/dep-id';
-import type { Graph } from '@vltpkg/graph';
+import type { Diff, Graph } from '@vltpkg/graph';
 import type { CommandFn, CommandUsage } from '../index.ts';
 /**
  * The resulting object of an install operation. To be used by the view impl.
@@ -14,15 +14,33 @@ export type InstallResult = {
      * The resulting graph structure at the end of an install.
      */
     graph: Graph;
+    /**
+     * The diff between the actual and ideal graphs, if available.
+     */
+    diff?: Diff;
 };
 export declare const usage: CommandUsage;
 export declare const views: {
     readonly json: (i: InstallResult) => {
-        graph: import("@vltpkg/graph").LockfileData;
         buildQueue?: DepID[] | undefined;
         message?: string | undefined;
+        add: {
+            name: string;
+            version?: string;
+        }[];
+        added: number;
+        change: {
+            name: string;
+            from?: string;
+            to?: string;
+        }[];
+        changed: number;
+        remove: {
+            name: string;
+            version?: string;
+        }[];
+        removed: number;
     };
     readonly human: typeof InstallReporter;
 };
 export declare const command: CommandFn<InstallResult>;
-//# sourceMappingURL=install.d.ts.map

package/dist/commands/install.js

@@ -0,0 +1,140 @@
+import { commandUsage } from "../config/usage.js";
+import { install } from '@vltpkg/graph';
+import { parseAddArgs } from "../parse-add-remove-args.js";
+import { InstallReporter } from "./install/reporter.js";
+import { trackInstall } from "../telemetry.js";
+export const usage = () => commandUsage({
+    command: 'install',
+    usage: '[packages ...]',
+    description: `Install the specified packages, updating package.json and
+                  vlt-lock.json appropriately.`,
+    options: {
+        'save-dev': {
+            description: 'Save installed packages to package.json as devDependencies.',
+        },
+        'save-optional': {
+            description: 'Save installed packages to package.json as optionalDependencies.',
+        },
+        'save-peer': {
+            description: 'Save installed packages to package.json as peerDependencies.',
+        },
+        'save-prod': {
+            description: 'Save installed packages to package.json as dependencies.',
+        },
+        workspace: {
+            value: '<path|glob>',
+            description: 'Limit installation targets to matching workspaces.',
+        },
+        'workspace-group': {
+            value: '<name>',
+            description: 'Limit installation targets to workspace groups.',
+        },
+        'expect-lockfile': {
+            description: 'Fail if lockfile is missing or out of date.',
+        },
+        'frozen-lockfile': {
+            description: 'Fail if lockfile is missing or out of sync with package.json.',
+        },
+        'lockfile-only': {
+            description: 'Only update lockfile and package.json files; skip node_modules operations.',
+        },
+        'allow-scripts': {
+            value: '<query>',
+            description: 'Filter which packages are allowed to run lifecycle scripts using DSS query syntax.',
+        },
+    },
+});
+export const views = {
+    json: i => {
+        const added = i.diff?.nodes.add ?? new Set();
+        const deleted = i.diff?.nodes.delete ?? new Set();
+        // The actual (from) graph represents what was on disk before the install.
+        // Used to filter out optional deps that were never installed (e.g.
+        // platform-specific binaries). These end up in the delete set via
+        // optionalFail but should not be reported as removals.
+        const actual = i.diff?.from;
+        // Build a map of deleted nodes by name for detecting changes
+        const deletedByName = new Map();
+        for (const node of deleted) {
+            if (node.importer)
+                continue;
+            // Skip nodes that were never on disk — these are optional deps
+            // that failed during install (e.g. wrong platform) and were moved
+            // to the delete set by optionalFail.
+            if (actual && !actual.nodes.has(node.id))
+                continue;
+            deletedByName.set(node.name, {
+                name: node.name,
+                version: node.version,
+            });
+        }
+        const add = [];
+        const change = [];
+        for (const node of added) {
+            if (node.importer)
+                continue;
+            const prev = deletedByName.get(node.name);
+            if (prev) {
+                // Package exists in both add and delete = changed
+                change.push({
+                    name: node.name,
+                    from: prev.version,
+                    to: node.version,
+                });
+                deletedByName.delete(node.name);
+            }
+            else {
+                add.push({ name: node.name, version: node.version });
+            }
+        }
+        // Remaining deleted nodes that weren't matched = pure removals
+        const remove = [...deletedByName.values()];
+        return {
+            add,
+            added: add.length,
+            change,
+            changed: change.length,
+            remove,
+            removed: remove.length,
+            ...(i.buildQueue?.length ?
+                {
+                    buildQueue: i.buildQueue,
+                    message: `${i.buildQueue.length} packages that will need to be built, run "vlt build" to complete the install.`,
+                }
+                : null),
+        };
+    },
+    human: InstallReporter,
+};
+export const command = async (conf) => {
+    // TODO: we should probably throw an error if the user
+    // tries to install using view=mermaid
+    const monorepo = conf.options.monorepo;
+    const scurry = conf.options.scurry;
+    const { add } = parseAddArgs(conf, scurry, monorepo);
+    const frozenLockfile = conf.options['frozen-lockfile'];
+    const expectLockfile = conf.options['expect-lockfile'];
+    const lockfileOnly = conf.options['lockfile-only'];
+    /* c8 ignore start */
+    const allowScripts = conf.get('allow-scripts') ?
+        String(conf.get('allow-scripts'))
+        : ':not(*)';
+    /* c8 ignore stop */
+    const installStart = Date.now();
+    const { buildQueue, graph, diff } = await install({
+        ...conf.options,
+        frozenLockfile,
+        expectLockfile,
+        allowScripts,
+        lockfileOnly,
+    }, add);
+    /* c8 ignore next 9 - telemetry is best-effort */
+    try {
+        trackInstall({
+            dependency_count: graph.nodes.size,
+            duration_ms: Date.now() - installStart,
+        }, conf.values.telemetry);
+    }
+    catch { }
+    return { buildQueue, graph, diff };
+};

package/dist/{esm/commands → commands}/list.d.ts

@@ -1,5 +1,6 @@
 import { humanReadableOutput, jsonOutput, mermaidOutput } from '@vltpkg/graph';
 import type { HumanReadableOutputGraph, JSONOutputGraph, MermaidOutputGraph } from '@vltpkg/graph';
+import { MermaidImageView } from '../mermaid-image-view.ts';
 import type { CommandFn, CommandUsage } from '../index.ts';
 export declare const usage: CommandUsage;
 export type ListResult = JSONOutputGraph & MermaidOutputGraph & HumanReadableOutputGraph & {
@@ -9,7 +10,8 @@ export declare const views: {
     readonly json: typeof jsonOutput;
     readonly mermaid: typeof mermaidOutput;
     readonly human: typeof humanReadableOutput;
-    readonly gui: ({ queryString }: ListResult, _: import("../view.ts").ViewOptions, conf: import("../config/index.ts").ParsedConfig) => Promise<void>;
+    readonly count: (result: ListResult) => number;
+    readonly svg: typeof MermaidImageView;
+    readonly png: typeof MermaidImageView;
 };
 export declare const command: CommandFn<ListResult>;
-//# sourceMappingURL=list.d.ts.map

package/dist/{esm/commands → commands}/list.js

@@ -1,17 +1,16 @@
 import { actual, asNode, humanReadableOutput, jsonOutput, mermaidOutput, GraphModifier, } from '@vltpkg/graph';
-import LZString from 'lz-string';
 import { Query } from '@vltpkg/query';
 import { SecurityArchive } from '@vltpkg/security-archive';
 import { error } from '@vltpkg/error-cause';
 import { commandUsage } from "../config/usage.js";
-import { startGUI } from "../start-gui.js";
 import { createHostContextsMap } from "../query-host-contexts.js";
+import { MermaidImageView } from "../mermaid-image-view.js";
 export const usage = () => commandUsage({
     command: 'ls',
     usage: [
         '',
-        '[package-names...] [--view=human | json | mermaid | gui]',
-        '[--scope=<query>] [--target=<query>] [--view=human | json | mermaid | gui]',
+        '[package-names...] [--view=human | json | mermaid | svg | png | count]',
+        '[--scope=<query>] [--target=<query>] [--view=human | json | mermaid | svg | png | count]',
     ],
     description: `List installed dependencies matching given package names or query selectors.
 
@@ -53,8 +52,8 @@ export const usage = () => commandUsage({
             description: 'Query selector to filter packages using the DSS query language syntax.',
         },
         view: {
-            value: '[human | json | mermaid | gui]',
-            description: 'Output format. Defaults to human-readable or json if no tty.',
+            value: '[human | json | mermaid | svg | png | count]',
+            description: 'Output format. Defaults to human-readable or json if no tty. Use svg or png to render the dependency graph as an image and open it. Count outputs the number of dependency relationships in the result.',
         },
     },
 });
@@ -62,9 +61,9 @@ export const views = {
     json: jsonOutput,
     mermaid: mermaidOutput,
     human: humanReadableOutput,
-    gui: async ({ queryString }, _, conf) => {
-        await startGUI(conf, `/explore/${LZString.compressToEncodedURIComponent(queryString)}/overview`);
-    },
+    count: (result) => result.edges.length,
+    svg: MermaidImageView,
+    png: MermaidImageView,
 };
 export const command = async (conf) => {
     const modifiers = GraphModifier.maybeLoad(conf.options);
@@ -196,4 +195,3 @@ export const command = async (conf) => {
                 : defaultLocalScopeQueryString),
     };
 };
-//# sourceMappingURL=list.js.map

package/dist/{esm/commands → commands}/login.d.ts

@@ -1,4 +1,3 @@
 import type { CommandFn, CommandUsage } from '../index.ts';
 export declare const usage: CommandUsage;
 export declare const command: CommandFn<void>;
-//# sourceMappingURL=login.d.ts.map

package/dist/{esm/commands → commands}/login.js

@@ -5,9 +5,18 @@ export const usage = () => commandUsage({
     usage: [''],
     description: `Authenticate against a registry, and store the token in
                   the appropriate config file for later use.`,
+    options: {
+        registry: {
+            value: '<url>',
+            description: 'Registry URL to authenticate against.',
+        },
+        identity: {
+            value: '<name>',
+            description: 'Identity namespace used to store auth tokens.',
+        },
+    },
 });
 export const command = async (conf) => {
     const rc = new RegistryClient(conf.options);
     await rc.login(conf.options.registry);
 };
-//# sourceMappingURL=login.js.map

package/dist/{esm/commands/token.d.ts → commands/logout.d.ts}

@@ -1,4 +1,3 @@
 import type { CommandFn, CommandUsage } from '../index.ts';
 export declare const usage: CommandUsage;
 export declare const command: CommandFn<void>;
-//# sourceMappingURL=token.d.ts.map

package/dist/{esm/commands → commands}/logout.js

@@ -5,9 +5,18 @@ export const usage = () => commandUsage({
     usage: [''],
     description: `Log out of the default registry, deleting the token from
                   the local keychain, as well as destroying it on the server.`,
+    options: {
+        registry: {
+            value: '<url>',
+            description: 'Registry URL to log out from.',
+        },
+        identity: {
+            value: '<name>',
+            description: 'Identity namespace used to look up auth tokens.',
+        },
+    },
 });
 export const command = async (conf) => {
     const rc = new RegistryClient(conf.options);
     await rc.logout(conf.options.registry);
 };
-//# sourceMappingURL=logout.js.map

package/dist/{esm/commands → commands}/pack.d.ts

@@ -29,4 +29,3 @@ export declare const commandSingle: (location: string, conf: LoadedConfig) => Pr
     shasum: string | undefined;
     integrity: string | undefined;
 }>;
-//# sourceMappingURL=pack.d.ts.map

package/dist/{esm/commands → commands}/pack.js

@@ -1,5 +1,5 @@
 import { writeFile } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import assert from 'node:assert';
 import { run } from '@vltpkg/run';
 import { commandUsage } from "../config/usage.js";
@@ -9,6 +9,7 @@ import { actual } from '@vltpkg/graph';
 import { Query } from '@vltpkg/query';
 import { error } from '@vltpkg/error-cause';
 import { createHostContextsMap } from "../query-host-contexts.js";
+import { minimatch } from 'minimatch';
 export const usage = () => commandUsage({
     command: 'pack',
     usage: '',
@@ -20,6 +21,21 @@ export const usage = () => commandUsage({
         'dry-run': {
             description: 'Show what would be packed without creating a tarball',
         },
+        scope: {
+            value: '<query>',
+            description: 'Filter packages to pack using a DSS query selector.',
+        },
+        workspace: {
+            value: '<path|glob>',
+            description: 'Limit pack targets to matching workspaces.',
+        },
+        'workspace-group': {
+            value: '<name>',
+            description: 'Limit pack targets to workspace groups.',
+        },
+        recursive: {
+            description: 'Pack all workspaces in the monorepo.',
+        },
     },
 });
 export const views = {
@@ -45,6 +61,43 @@ export const views = {
     },
     json: r => r,
 };
+/**
+ * Resolve a scope query string to workspace locations using the DSS query system.
+ */
+const scopeLocations = async (queryString, conf) => {
+    const { options, projectRoot } = conf;
+    const mainManifest = options.packageJson.maybeRead(projectRoot);
+    let graph;
+    if (mainManifest) {
+        graph = actual.load({
+            ...options,
+            mainManifest,
+            monorepo: options.monorepo,
+            loadManifests: false,
+        });
+    }
+    const hostContexts = await createHostContextsMap(conf);
+    const query = new Query({
+        /* c8 ignore next */
+        nodes: graph ? new Set(graph.nodes.values()) : new Set(),
+        edges: graph?.edges ?? new Set(),
+        importers: graph?.importers ?? new Set(),
+        securityArchive: undefined,
+        hostContexts,
+    });
+    const { nodes } = await query.search(queryString, {
+        signal: new AbortController().signal,
+    });
+    const locations = [];
+    for (const node of nodes) {
+        const { location } = node.toJSON();
+        assert(location, error(`node ${node.id} has no location`, {
+            found: node,
+        }));
+        locations.push(resolve(projectRoot, location));
+    }
+    return locations;
+};
 export const command = async (conf) => {
     const { options, projectRoot } = conf;
     const queryString = conf.get('scope');
@@ -54,41 +107,43 @@ export const command = async (conf) => {
     const locations = [];
     let single = null;
     if (queryString) {
-        const mainManifest = options.packageJson.maybeRead(projectRoot);
-        let graph;
-        if (mainManifest) {
-            graph = actual.load({
-                ...options,
-                mainManifest,
-                monorepo: options.monorepo,
-                loadManifests: false,
-            });
-        }
-        const hostContexts = await createHostContextsMap(conf);
-        const query = new Query({
-            /* c8 ignore next */
-            nodes: graph ? new Set(graph.nodes.values()) : new Set(),
-            edges: graph?.edges ?? new Set(),
-            importers: graph?.importers ?? new Set(),
-            securityArchive: undefined,
-            hostContexts,
-        });
-        const { nodes } = await query.search(queryString, {
-            signal: new AbortController().signal,
-        });
-        for (const node of nodes) {
-            const { location } = node.toJSON();
-            assert(location, error(`node ${node.id} has no location`, {
-                found: node,
-            }));
-            locations.push(resolve(projectRoot, location));
-        }
+        locations.push(...(await scopeLocations(queryString, conf)));
     }
     else if (paths?.length || groups?.length || recursive) {
         for (const workspace of options.monorepo ?? []) {
+            // When specific workspace paths are set (including auto-inferred from cwd),
+            // filter to only matching workspaces. Without this, all monorepo workspaces
+            // would be operated on even when only one was specified.
+            if (paths?.length) {
+                const matches = paths.some((p) => workspace.path === p ||
+                    workspace.name === p ||
+                    workspace.fullpath === p ||
+                    resolve(projectRoot, p) === workspace.fullpath ||
+                    minimatch(workspace.path, p));
+                if (!matches)
+                    continue;
+            }
             locations.push(workspace.fullpath);
         }
     }
+    else if (options.monorepo) {
+        const cwd = process.cwd();
+        if (cwd === projectRoot) {
+            for (const workspace of options.monorepo) {
+                locations.push(workspace.fullpath);
+            }
+        }
+        else {
+            const ws = options.monorepo.get(cwd);
+            if (ws) {
+                locations.push(ws.fullpath);
+            }
+            else {
+                const rel = relative(projectRoot, cwd).replaceAll('\\', '/');
+                locations.push(...(await scopeLocations(`:path("${rel}")`, conf)));
+            }
+        }
+    }
     else {
         single = options.packageJson.find(process.cwd()) ?? projectRoot;
     }
@@ -124,7 +179,11 @@ export const commandSingle = async (location, conf) => {
         ...runOptions,
         arg0: 'prepare',
     });
-    const { name, version, filename, tarballData, unpackedSize, files, integrity, shasum, } = await packTarball(manifest, manifestDir, conf);
+    // Re-read the manifest after lifecycle scripts, which may have modified package.json.
+    const updatedManifest = conf.options.packageJson.read(manifestDir, {
+        reload: true,
+    });
+    const { name, version, filename, tarballData, unpackedSize, files, integrity, shasum, } = await packTarball(updatedManifest, manifestDir, conf);
     if (!isDryRun) {
         await writeFile(join(manifestDir, filename), tarballData);
     }
@@ -144,4 +203,3 @@ export const commandSingle = async (location, conf) => {
         integrity,
     };
 };
-//# sourceMappingURL=pack.js.map

package/dist/commands/ping.d.ts

@@ -0,0 +1,17 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const usage: CommandUsage;
+type PingResult = {
+    registry: string;
+    alias?: string;
+    status: 'ok' | 'error';
+    time: number;
+    statusCode?: number;
+    error?: string;
+};
+type CommandResult = PingResult | PingResult[];
+export declare const views: {
+    readonly human: (r: CommandResult) => string;
+    readonly json: (r: CommandResult) => CommandResult;
+};
+export declare const command: CommandFn<CommandResult>;
+export {};

package/dist/commands/ping.js

@@ -0,0 +1,114 @@
+import { RegistryClient } from '@vltpkg/registry-client';
+import { error } from '@vltpkg/error-cause';
+import { commandUsage } from "../config/usage.js";
+export const usage = () => commandUsage({
+    command: 'ping',
+    usage: ['', '[<registry-alias>]'],
+    description: `Ping configured registries to verify connectivity
+                  and check registry health.
+
+                  By default, pings all configured registries including
+                  the default registry.
+
+                  If a registry alias is provided, ping only that specific
+                  registry. Registry aliases are configured via the
+                  \`registries\` field in vlt.json or with the
+                  \`--registries\` option.`,
+    options: {
+        registry: {
+            value: '<url>',
+            description: 'The default registry URL to ping.',
+        },
+        registries: {
+            value: '<alias=url>',
+            description: 'Named registry aliases to ping.',
+        },
+    },
+});
+const formatPingResult = (r) => {
+    const prefix = r.alias ? `${r.alias} (${r.registry})` : r.registry;
+    if (r.status === 'ok') {
+        return `Ping successful: ${prefix} (${r.time}ms)`;
+    }
+    else {
+        return `Ping failed: ${prefix} - ${r.error}`;
+    }
+};
+export const views = {
+    human: r => {
+        if (Array.isArray(r)) {
+            return r.map(formatPingResult).join('\n');
+        }
+        return formatPingResult(r);
+    },
+    json: r => r,
+};
+const pingRegistry = async (rc, registry, alias) => {
+    const url = new URL('-/ping?write=true', registry);
+    const start = Date.now();
+    try {
+        const response = await rc.request(url, { useCache: false });
+        const time = Date.now() - start;
+        if (response.statusCode >= 200 && response.statusCode < 300) {
+            return {
+                registry,
+                alias,
+                status: 'ok',
+                time,
+                statusCode: response.statusCode,
+            };
+        }
+        else {
+            return {
+                registry,
+                alias,
+                status: 'error',
+                time,
+                statusCode: response.statusCode,
+                error: `Registry returned status ${response.statusCode}`,
+            };
+        }
+    }
+    catch (err) {
+        const time = Date.now() - start;
+        return {
+            registry,
+            alias,
+            status: 'error',
+            time,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+};
+export const command = async (conf) => {
+    const rc = new RegistryClient(conf.options);
+    const registryAlias = conf.positionals[0];
+    if (registryAlias) {
+        // Ping a specific registry by alias
+        const registries = conf.options.registries;
+        const registry = registries[registryAlias];
+        if (!registry) {
+            const availableAliases = Object.keys(registries);
+            throw error('Unknown registry alias', {
+                found: registryAlias,
+                wanted: availableAliases.length > 0 ? availableAliases : undefined,
+            });
+        }
+        return await pingRegistry(rc, registry, registryAlias);
+    }
+    else {
+        // Ping all configured registries
+        const registries = conf.options.registries;
+        const results = [];
+        // Always ping the default registry first
+        results.push(await pingRegistry(rc, conf.options.registry, 'default'));
+        // Then ping all configured registry aliases
+        for (const [alias, registry] of Object.entries(registries)) {
+            // Skip if it's the same as the default registry
+            if (registry !== conf.options.registry) {
+                results.push(await pingRegistry(rc, registry, alias));
+            }
+        }
+        return results;
+    }
+};

package/dist/{esm/commands → commands}/pkg.d.ts

@@ -4,4 +4,3 @@ export declare const views: {
 };
 export declare const usage: CommandUsage;
 export declare const command: CommandFn;
-//# sourceMappingURL=pkg.d.ts.map

package/dist/{esm/commands → commands}/pkg.js

@@ -9,6 +9,7 @@ import { SecurityArchive } from '@vltpkg/security-archive';
 import { views as initViews } from "./init.js";
 import { commandUsage } from "../config/usage.js";
 import { createHostContextsMap } from "../query-host-contexts.js";
+import { minimatch } from 'minimatch';
 export const views = {
     human: (results, _, config) => {
         // `vlt pkg init` is an alias for `vlt init`
@@ -58,6 +59,23 @@ export const usage = () => commandUsage({
             description: 'Append a value to an array',
         },
     },
+    options: {
+        scope: {
+            value: '<query>',
+            description: 'Filter package.json targets using a DSS query.',
+        },
+        workspace: {
+            value: '<path|glob>',
+            description: 'Limit package.json targets to matching workspaces.',
+        },
+        'workspace-group': {
+            value: '<name>',
+            description: 'Limit package.json targets to workspace groups.',
+        },
+        recursive: {
+            description: 'Operate across all workspaces in the current monorepo.',
+        },
+    },
 });
 export const command = async (conf) => {
     const [sub, ...args] = conf.positionals;
@@ -123,6 +141,15 @@ export const command = async (conf) => {
     }
     else if (paths?.length || groups?.length || recursive) {
         for (const workspace of options.monorepo ?? []) {
+            if (paths?.length) {
+                const matches = paths.some((p) => workspace.path === p ||
+                    workspace.name === p ||
+                    workspace.fullpath === p ||
+                    resolve(projectRoot, p) === workspace.fullpath ||
+                    minimatch(workspace.path, p));
+                if (!matches)
+                    continue;
+            }
             locations.push(workspace.fullpath);
         }
     }
@@ -203,4 +230,3 @@ const rm = (manifest, location, pkg, args) => {
         location,
     };
 };
-//# sourceMappingURL=pkg.js.map