@vltpkg/cli-sdk 1.0.0-rc.22 → 1.0.0-rc.24

package/dist/commands/bugs.d.ts

@@ -0,0 +1,17 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const usage: CommandUsage;
+type CommandResultSingle = {
+    url: string;
+    name: string;
+};
+type CommandResultMultiple = {
+    url: string;
+    name: string;
+}[];
+export type CommandResult = CommandResultSingle | CommandResultMultiple;
+export declare const views: {
+    readonly human: (r: CommandResult) => string;
+    readonly json: (r: CommandResult) => CommandResult;
+};
+export declare const command: CommandFn<CommandResult>;
+export {};

package/dist/commands/bugs.js

@@ -0,0 +1,163 @@
+import { error } from '@vltpkg/error-cause';
+import { PackageInfoClient } from '@vltpkg/package-info';
+import { Spec } from '@vltpkg/spec';
+import { urlOpen } from '@vltpkg/url-open';
+import { actual } from '@vltpkg/graph';
+import { Query } from '@vltpkg/query';
+import { SecurityArchive } from '@vltpkg/security-archive';
+import { createHostContextsMap } from "../query-host-contexts.js";
+import { commandUsage } from "../config/usage.js";
+import hostedGitInfo from 'hosted-git-info';
+const { fromUrl: hostedGitInfoFromUrl } = hostedGitInfo;
+export const usage = () => commandUsage({
+    command: 'bugs',
+    usage: ['[<spec>]', '[--target=<query>]'],
+    description: `Open bug tracker for a package in a web browser.
+                  Reads bug tracker information from package.json or fetches
+                  manifest data for the specified package.`,
+    options: {
+        target: {
+            value: '<query>',
+            description: 'Query selector to filter packages using DSS syntax.',
+        },
+    },
+    examples: {
+        '': {
+            description: 'Open bugs for the current package (reads local package.json)',
+        },
+        'abbrev@2.0.0': {
+            description: 'Open bugs for a specific package version',
+        },
+        '--target=":root > *"': {
+            description: 'List bug tracker URLs for all direct dependencies',
+        },
+    },
+});
+export const views = {
+    human: r => {
+        if (Array.isArray(r)) {
+            let msg = 'Multiple package bug trackers found:\n';
+            msg += r.map(item => `• ${item.name}: ${item.url}`).join('\n');
+            return msg;
+        }
+        return '';
+    },
+    json: r => r,
+};
+const getUrlFromManifest = (manifest) => {
+    const { name, bugs, repository } = manifest;
+    if (!name) {
+        throw error('No package name found');
+    }
+    let url;
+    // Check bugs field first
+    if (bugs) {
+        if (typeof bugs === 'string') {
+            url = bugs;
+        }
+        else if (typeof bugs === 'object') {
+            if ('url' in bugs && bugs.url) {
+                url = bugs.url;
+            }
+            else if ('email' in bugs && bugs.email) {
+                url = `mailto:${bugs.email}`;
+            }
+        }
+    }
+    // Try repository if no bugs field
+    if (!url && repository) {
+        const repoUrl = typeof repository === 'string' ? repository
+            : typeof repository === 'object' && 'url' in repository ?
+                repository.url
+                : /* c8 ignore next */ undefined;
+        if (repoUrl) {
+            const info = hostedGitInfoFromUrl(repoUrl.replace(/^git\+/, ''));
+            if (info?.bugs && typeof info.bugs === 'function') {
+                url = info.bugs();
+            }
+        }
+    }
+    // Fallback to vlt.io package page
+    if (!url) {
+        url = `https://vlt.io/explore/npm/${name}/overview`;
+    }
+    return url;
+};
+export const command = async (conf) => {
+    const { projectRoot, packageJson } = conf.options;
+    const targetOption = conf.get('target');
+    // Handle --target query
+    if (targetOption) {
+        const mainManifest = packageJson.maybeRead(projectRoot);
+        if (!mainManifest) {
+            throw error('No package.json found in project root', {
+                path: projectRoot,
+            });
+        }
+        const graph = actual.load({
+            ...conf.options,
+            mainManifest,
+            monorepo: conf.options.monorepo,
+            loadManifests: true,
+        });
+        const securityArchive = Query.hasSecuritySelectors(targetOption) ?
+            await SecurityArchive.start({
+                nodes: [...graph.nodes.values()],
+            })
+            : undefined;
+        const hostContexts = await createHostContextsMap(conf);
+        const query = new Query({
+            nodes: new Set(graph.nodes.values()),
+            edges: graph.edges,
+            importers: graph.importers,
+            securityArchive,
+            hostContexts,
+        });
+        const { nodes } = await query.search(targetOption, {
+            signal: new AbortController().signal,
+        });
+        const results = [];
+        for (const node of nodes) {
+            if (!node.manifest)
+                continue;
+            const url = getUrlFromManifest(node.manifest);
+            results.push({
+                url,
+                name: node.name /* c8 ignore next */ ?? '(unknown)',
+            });
+        }
+        if (results.length === 0) {
+            throw error('No packages found matching target query', {
+                found: targetOption,
+            });
+        }
+        // If single result, open it
+        if (results.length === 1) {
+            const result = results[0];
+            /* c8 ignore next 3 */
+            if (!result) {
+                throw error('Unexpected empty result');
+            }
+            await urlOpen(result.url);
+            return result;
+        }
+        // Multiple results, return the list
+        return results;
+    }
+    // read the package spec from a positional argument or local package.json
+    const specArg = conf.positionals[0];
+    const manifest = conf.positionals.length === 0 ? packageJson.read(projectRoot)
+        : specArg ?
+            await new PackageInfoClient(conf.options).manifest(Spec.parseArgs(specArg, conf.options))
+            : /* c8 ignore next */ packageJson.read(projectRoot);
+    const url = getUrlFromManifest(manifest);
+    const { name } = manifest;
+    /* c8 ignore start - getUrlFromManifest already validates name */
+    if (!name) {
+        throw error('No package name found');
+    }
+    /* c8 ignore stop */
+    // Open the URL
+    await urlOpen(url);
+    return { url, name };
+};

package/dist/commands/build.d.ts

@@ -0,0 +1,24 @@
+import type { BuildResult } from '@vltpkg/graph';
+import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const views: {
+    readonly human: (result: BuildResult) => string;
+    readonly json: (result: BuildResult) => {
+        success: {
+            id: import("@vltpkg/dep-id").DepID;
+            name: string;
+            version: string | undefined;
+        }[];
+        failure: {
+            id: import("@vltpkg/dep-id").DepID;
+            name: string;
+            version: string | undefined;
+        }[];
+        message: string;
+    };
+};
+export declare const usage: CommandUsage;
+/**
+ * Build command implementation. Runs any required "postinstall"
+ * lifecycle scripts and binary linking.
+ */
+export declare const command: CommandFn<BuildResult>;

package/dist/commands/build.js

@@ -0,0 +1,101 @@
+import { build } from '@vltpkg/graph';
+import { error } from '@vltpkg/error-cause';
+import { commandUsage } from "../config/usage.js";
+import { isErrorWithCause } from '@vltpkg/types';
+export const views = {
+    human: (result) => {
+        const successCount = result.success.length;
+        const failureCount = result.failure.length;
+        const messages = [];
+        if (successCount > 0) {
+            messages.push(`🔨 Built ${successCount} package${successCount === 1 ? '' : 's'} successfully.`);
+        }
+        else {
+            messages.push('📦 All packages are already built.');
+        }
+        if (failureCount > 0) {
+            messages.push(`🔎 ${failureCount} optional package${ /* c8 ignore next */failureCount === 1 ? '' : 's'} failed to build.`);
+        }
+        return messages.join('\n');
+    },
+    json: (result) => {
+        const successList = result.success.map(node => ({
+            id: node.id,
+            name: node.name,
+            version: node.version,
+        }));
+        const failureList = result.failure.map(node => ({
+            id: node.id,
+            name: node.name,
+            version: node.version,
+        }));
+        return {
+            success: successList,
+            failure: failureList,
+            message: successList.length > 0 ?
+                `Built ${successList.length} package${successList.length === 1 ? '' : 's'}.`
+                : 'No packages needed building.',
+        };
+    },
+};
+export const usage = () => commandUsage({
+    command: 'build',
+    usage: ['[query]', '[--target=<query>]'],
+    description: `Build the project based on the current dependency graph.
+
+    This command processes the installed packages in node_modules and runs
+    any necessary build steps, such as lifecycle scripts and binary linking.
+    
+    The build process is idempotent and will only perform work that is
+    actually needed based on the current state of the dependency graph.
+    
+    Use --target option or provide a query as a positional argument to filter
+    packages using DSS query language syntax, otherwise it will target
+    all packages with scripts (:scripts) by default.`,
+    options: {
+        target: {
+            value: '<query>',
+            description: 'Query selector to filter packages using DSS syntax.',
+        },
+    },
+});
+const isGraphRunError = (error) => typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    error.code === 'GRAPHRUN_TRAVERSAL' &&
+    'node' in error;
+/**
+ * Build command implementation. Runs any required "postinstall"
+ * lifecycle scripts and binary linking.
+ */
+export const command = async (conf) => {
+    const { options, projectRoot } = conf;
+    try {
+        // Get target from option or first positional, default to all scripts
+        const targetOption = conf.get('target');
+        const targetPositional = conf.positionals[0];
+        const target = targetOption ||
+            targetPositional ||
+            ':scripts:not(:built):not(:malware)';
+        // Run the build process using the graph build function
+        const result = await build({
+            ...options,
+            projectRoot,
+            packageJson: options.packageJson,
+            monorepo: options.monorepo,
+            scurry: options.scurry,
+            target,
+        });
+        return result;
+    }
+    catch (cause) {
+        const graphRunError = isErrorWithCause(cause) && isGraphRunError(cause.cause) ?
+            cause.cause
+            : undefined;
+        if (graphRunError?.code === 'GRAPHRUN_TRAVERSAL') {
+            throw error('Build failed:\n  Failed to build package: ' +
+                `${graphRunError.node.name}@${graphRunError.node.version}`, { cause });
+        }
+        throw error('Build failed', { cause });
+    }
+};

package/dist/commands/cache.d.ts

@@ -0,0 +1,64 @@
+import { CacheEntry } from '@vltpkg/registry-client';
+import type { LoadedConfig } from '../config/index.ts';
+import type { CommandFn, CommandUsage } from '../index.ts';
+import type { ViewOptions, Views } from '../view.ts';
+import { ViewClass } from '../view.ts';
+export type CacheMap = Record<string, ReturnType<CacheEntry['toJSON']>>;
+export type CacheSubcommands = keyof (typeof usageDef)['subcommands'];
+export declare class CacheView extends ViewClass {
+    constructor(options: ViewOptions, conf: LoadedConfig);
+    stdout(...args: unknown[]): void;
+}
+export declare const views: Views<void | CacheMap>;
+declare const usageDef: {
+    readonly command: "cache";
+    readonly usage: "<command> [flags]";
+    readonly description: "Work with vlt cache folders";
+    readonly subcommands: {
+        readonly add: {
+            readonly usage: "<package-spec> [<package-spec>...]";
+            readonly description: "Resolve the referenced package identifiers and ensure they\n                    are cached.";
+        };
+        readonly ls: {
+            readonly usage: "[<key>...]";
+            readonly description: "Show cache entries. If no keys are provided, then a list of\n                    available keys will be printed. If one or more keys are\n                    provided, then details will be shown for the specified\n                    items.";
+        };
+        readonly info: {
+            readonly usage: "<key>";
+            readonly description: "Print metadata details for the specified cache key to\n                    stderr, and the response body to stdout.";
+        };
+        readonly clean: {
+            readonly usage: "[<key>...]";
+            readonly description: "Purge expired cache entries. If one or more keys are\n                    provided, then only those cache entries will be\n                    considered.";
+        };
+        readonly delete: {
+            readonly usage: "<key> [<key>...]";
+            readonly description: "Purge items explicitly, whether expired or not.  If one or\n                    more keys are provided, then only those cache entries will\n                    be considered.";
+        };
+        readonly 'delete-before': {
+            readonly usage: "<date>";
+            readonly description: "Purge all cache items from before a given date. Date can be\n                    provided in any format that JavaScript can parse.";
+        };
+        readonly 'delete-all': {
+            readonly usage: "";
+            readonly description: "Delete the entire cache folder to make vlt slower.";
+        };
+    };
+    readonly examples: {
+        readonly 'vlt cache ls https://registry.npmjs.org/typescript': {
+            readonly description: "Show cache metadata for a given registry URL";
+        };
+        readonly 'vlt cache add eslint@latest': {
+            readonly description: "Add a given package specifier to the cache by fetching\n                    its resolved value.";
+        };
+        readonly 'vlt cache info https://registry.npmjs.org/eslint/-/eslint-9.25.1.tgz > eslint.tgz': {
+            readonly description: "Print the cache metadata to stderr, and write the tarball\n                    on stdout, redirecting to a file.";
+        };
+        readonly 'vlt cache delete-before 2025-01-01': {
+            readonly description: "Delete all entries created before Jan 1, 2025";
+        };
+    };
+};
+export declare const usage: CommandUsage;
+export declare const command: CommandFn<void | CacheMap>;
+export {};

package/dist/commands/cache.js

@@ -0,0 +1,256 @@
+import { error } from '@vltpkg/error-cause';
+import { CacheEntry } from '@vltpkg/registry-client';
+import { Spec } from '@vltpkg/spec';
+import { mkdir, rm } from 'node:fs/promises';
+import prettyBytes from 'pretty-bytes';
+import { commandUsage } from "../config/usage.js";
+import { stderr, stdout } from "../output.js";
+import { ViewClass } from "../view.js";
+let view;
+export class CacheView extends ViewClass {
+    constructor(options, conf) {
+        super(options, conf);
+        view = this;
+    }
+    stdout(...args) {
+        stdout(...args);
+    }
+}
+export const views = {
+    human: CacheView,
+};
+const usageDef = {
+    command: 'cache',
+    usage: '<command> [flags]',
+    description: 'Work with vlt cache folders',
+    subcommands: {
+        add: {
+            usage: '<package-spec> [<package-spec>...]',
+            description: `Resolve the referenced package identifiers and ensure they
+                    are cached.`,
+        },
+        ls: {
+            usage: '[<key>...]',
+            description: `Show cache entries. If no keys are provided, then a list of
+                    available keys will be printed. If one or more keys are
+                    provided, then details will be shown for the specified
+                    items.`,
+        },
+        info: {
+            usage: '<key>',
+            description: `Print metadata details for the specified cache key to
+                    stderr, and the response body to stdout.`,
+        },
+        clean: {
+            usage: '[<key>...]',
+            description: `Purge expired cache entries. If one or more keys are
+                    provided, then only those cache entries will be
+                    considered.`,
+        },
+        delete: {
+            usage: '<key> [<key>...]',
+            description: `Purge items explicitly, whether expired or not.  If one or
+                    more keys are provided, then only those cache entries will
+                    be considered.`,
+        },
+        'delete-before': {
+            usage: '<date>',
+            description: `Purge all cache items from before a given date. Date can be
+                    provided in any format that JavaScript can parse.`,
+        },
+        'delete-all': {
+            usage: '',
+            description: `Delete the entire cache folder to make vlt slower.`,
+        },
+    },
+    examples: {
+        'vlt cache ls https://registry.npmjs.org/typescript': {
+            description: `Show cache metadata for a given registry URL`,
+        },
+        'vlt cache add eslint@latest': {
+            description: `Add a given package specifier to the cache by fetching
+                    its resolved value.`,
+        },
+        'vlt cache info https://registry.npmjs.org/eslint/-/eslint-9.25.1.tgz > eslint.tgz': {
+            description: `Print the cache metadata to stderr, and write the tarball
+                    on stdout, redirecting to a file.`,
+        },
+        'vlt cache delete-before 2025-01-01': {
+            description: 'Delete all entries created before Jan 1, 2025',
+        },
+    },
+};
+export const usage = () => commandUsage(usageDef);
+export const command = async (conf) => {
+    const [sub, ...args] = conf.positionals;
+    switch (sub) {
+        case 'ls':
+            return ls(conf, args, view);
+        case 'info':
+            return info(conf, args, view);
+        case 'add':
+            return add(conf, args, view);
+        case 'clean':
+            return clean(conf, args, view);
+        case 'delete':
+            return deleteKeys(conf, args, view);
+        case 'delete-before':
+            return deleteBefore(conf, args, view);
+        case 'delete-all':
+            return deleteAll(conf, args, view);
+        default: {
+            throw error('Unrecognized cache command', {
+                code: 'EUSAGE',
+                found: sub,
+                validOptions: Object.keys(usageDef.subcommands),
+            });
+        }
+    }
+};
+const ls = async (conf, keys, view) => keys.length ?
+    await fetchKeys(conf, keys, (entry, key) => {
+        view?.stdout(key.includes(' ') ? JSON.stringify(key) : key, entry);
+        return true;
+    }, view)
+    : await fetchAll(conf, (_, key) => {
+        view?.stdout(key.includes(' ') ? JSON.stringify(key) : key);
+        return true;
+    });
+const info = async (conf, keys, view) => {
+    const [key] = keys;
+    if (keys.length !== 1 || !key) {
+        throw error('Must provide exactly one cache key', {
+            code: 'EUSAGE',
+        });
+    }
+    await fetchKeys(conf, [key], (entry, key) => {
+        stderr(
+        /* c8 ignore next */
+        key.includes(' ') ? JSON.stringify(key) : key, entry);
+        if (entry.isJSON) {
+            stdout(JSON.stringify(entry.body, null, 2));
+            /* c8 ignore start - annoying to test, corrupts TAP output */
+        }
+        else {
+            process.stdout.write(entry.body);
+        }
+        /* c8 ignore stop */
+        return true;
+    }, view);
+};
+const fetchAll = async (conf, test) => {
+    const rc = conf.options.packageInfo.registryClient;
+    const { cache } = rc;
+    const map = {};
+    for await (const [key, val] of cache) {
+        const entry = CacheEntry.decode(val);
+        if (!test(entry, key, val))
+            continue;
+        map[key] = entry.toJSON();
+    }
+    return map;
+};
+const fetchKeys = async (conf, keys, test, view) => {
+    const rc = conf.options.packageInfo.registryClient;
+    const { cache } = rc;
+    const map = {};
+    const results = await Promise.all(keys.map(async (key) => {
+        return [key, await cache.fetch(key)];
+    }));
+    for (const [key, val] of results) {
+        if (!val) {
+            view?.stdout('Not found:', key);
+        }
+        else {
+            const entry = CacheEntry.decode(val);
+            if (!test(entry, key, val))
+                continue;
+            map[key] = entry.toJSON();
+        }
+    }
+    return map;
+};
+const deleteEntries = async (conf, keys, test, view) => {
+    const rc = conf.options.packageInfo.registryClient;
+    const { cache } = rc;
+    let count = 0;
+    let size = 0;
+    const testAction = (entry, key, val) => {
+        if (!test(entry)) {
+            return false;
+        }
+        count++;
+        const s = val.byteLength + key.length;
+        cache.delete(key, true, entry.integrity);
+        const k = key.includes(' ') ? JSON.stringify(key) : key;
+        view?.stdout('-', k, s);
+        size += s;
+        return true;
+    };
+    const map = await (keys.length ?
+        fetchKeys(conf, keys, testAction, view)
+        : fetchAll(conf, testAction));
+    const pb = prettyBytes(size, { binary: true });
+    const s = count === 1 ? '' : 's';
+    await cache.promise();
+    view?.stdout(`Removed ${count} item${s} totalling ${pb}`);
+    return map;
+};
+const clean = async (conf, keys, view) => deleteEntries(conf, keys, entry => !entry.valid, view);
+const deleteBefore = async (conf, args, view) => {
+    if (!args.length) {
+        throw error('Must provide a date to delete before', {
+            code: 'EUSAGE',
+        });
+    }
+    const now = new Date();
+    const before = new Date(args.join(' '));
+    if (before >= now) {
+        throw error('Cannot delete cache entries from the future', {
+            code: 'EUSAGE',
+            found: before,
+        });
+    }
+    return deleteEntries(conf, [], entry => !!entry.date && entry.date < before, view);
+};
+const deleteKeys = async (conf, keys, view) => {
+    if (!keys.length) {
+        throw error('Must provide cache keys to delete', {
+            code: 'EUSAGE',
+        });
+    }
+    return deleteEntries(conf, keys, () => true, view);
+};
+const deleteAll = async (conf, _, view) => {
+    const { cache } = conf.options.packageInfo.registryClient;
+    await rm(cache.path(), { recursive: true, force: true });
+    await mkdir(cache.path(), { recursive: true });
+    view?.stdout('Deleted all cache entries.');
+};
+const add = async (conf, specs, view) => {
+    if (!specs.length) {
+        throw error('Must provide specs to add to the cache', {
+            code: 'EUSAGE',
+        });
+    }
+    const { packageInfo } = conf.options;
+    const promises = [];
+    for (const spec of specs) {
+        const p = packageInfo
+            .resolve(Spec.parseArgs(spec, conf.options), {
+            staleWhileRevalidate: false,
+        })
+            .then(async (r) => {
+            const { resolved, integrity } = r;
+            await packageInfo.registryClient.request(resolved, {
+                ...conf.options,
+                integrity,
+                staleWhileRevalidate: false,
+                query: undefined,
+            });
+            view?.stdout('+', spec, r.resolved);
+        });
+        promises.push(p);
+    }
+    await Promise.all(promises);
+};

package/dist/commands/ci.d.ts

@@ -0,0 +1,10 @@
+import { InstallReporter } from './install/reporter.ts';
+import type { CommandFn, CommandUsage } from '../index.ts';
+import type { InstallResult } from './install.ts';
+export type CIResult = Omit<InstallResult, 'buildQueue'>;
+export declare const usage: CommandUsage;
+export declare const views: {
+    readonly json: (i: CIResult) => import("@vltpkg/graph").LockfileData;
+    readonly human: typeof InstallReporter;
+};
+export declare const command: CommandFn<CIResult>;

package/dist/commands/ci.js

@@ -0,0 +1,40 @@
+import { install } from '@vltpkg/graph';
+import { commandUsage } from "../config/usage.js";
+import { InstallReporter } from "./install/reporter.js";
+export const usage = () => commandUsage({
+    command: 'ci',
+    usage: '',
+    description: `Clean install from lockfile. Deletes node_modules and installs 
+                  dependencies exactly as specified in vlt-lock.json. This is 
+                  similar to running 'vlt install --expect-lockfile' but performs 
+                  a clean install by removing node_modules first.`,
+    examples: {
+        '': { description: 'Clean install from lockfile' },
+    },
+    options: {
+        'allow-scripts': {
+            value: '<query>',
+            description: 'Filter which packages are allowed to run lifecycle scripts using DSS query syntax.',
+        },
+        'lockfile-only': {
+            description: 'Only update lockfile and package.json files; skip node_modules operations.',
+        },
+    },
+});
+export const views = {
+    json: i => i.graph.toJSON(),
+    human: InstallReporter,
+};
+export const command = async (conf) => {
+    const ciOptions = {
+        ...conf.options,
+        // allow scripts but filter out malware via security archive
+        allowScripts: conf.get('allow-scripts') ?? ':scripts:not(:malware)',
+        expectLockfile: true,
+        frozenLockfile: true,
+        cleanInstall: true,
+        lockfileOnly: conf.options['lockfile-only'],
+    };
+    const { graph } = await install(ciOptions);
+    return { graph };
+};

package/dist/commands/config.d.ts

@@ -0,0 +1,5 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+import type { Views } from '../view.ts';
+export declare const views: Views;
+export declare const usage: CommandUsage;
+export declare const command: CommandFn;