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

package/dist/commands/init.js

@@ -0,0 +1,116 @@
+import { mkdirSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { minimatch } from 'minimatch';
+import { init } from '@vltpkg/init';
+import { load, save } from '@vltpkg/vlt-json';
+import { assertWSConfig, asWSConfig } from '@vltpkg/workspaces';
+import { commandUsage } from "../config/usage.js";
+export const usage = () => commandUsage({
+    command: 'init',
+    usage: '',
+    description: `Create a new package.json file in the current directory.`,
+    options: {
+        workspace: {
+            value: '<path|glob>',
+            description: 'Create package.json files in matching workspaces.',
+        },
+    },
+});
+// TODO: colorize the JSON if config.options.color
+export const views = {
+    human: (results) => {
+        const output = [];
+        // if results is an array, it means multiple workspaces were initialized
+        if (Array.isArray(results)) {
+            for (const result of results) {
+                for (const [type, { path }] of Object.entries(result)) {
+                    output.push(`Wrote ${type} to ${path}:`);
+                }
+            }
+        }
+        else {
+            // otherwise, it's a single result
+            for (const [type, { path, data }] of Object.entries(results)) {
+                output.push(`Wrote ${type} to ${path}:
+
+${JSON.stringify(data, null, 2)}`);
+            }
+        }
+        output.push(`\nModify/add properties using \`vlt pkg\`. For example:
+
+  vlt pkg set "description=My new project"`);
+        return output.join('\n');
+    },
+};
+export const command = async (conf) => {
+    if (conf.values.workspace?.length) {
+        const workspacesConfig = load('workspaces', assertWSConfig);
+        const parsedWSConfig = asWSConfig(workspacesConfig ?? {});
+        const results = [];
+        const addToConfig = [];
+        // create a new package.json file for every workspace
+        // defined as cli --workspace options
+        for (const workspace of conf.values.workspace) {
+            // cwd is the resolved location of the workspace
+            const cwd = resolve(conf.options.projectRoot, workspace);
+            // create the folder in case it's missing
+            mkdirSync(cwd, { recursive: true });
+            // run the initialization script and collect results
+            results.push(await init({ cwd }));
+            // Check if this workspace path is covered by existing workspace patterns
+            const isMatched = Object.values(parsedWSConfig).some((patterns) => {
+                return patterns.some(pattern => minimatch(workspace, pattern));
+            });
+            // When a workspace is not matched we track it for insertion later
+            if (!isMatched) {
+                addToConfig.push(relative(conf.options.projectRoot, cwd).replace(/\\/g, '/'));
+            }
+        }
+        // if there are workspaces that were not matched by existing
+        // patterns, we add them to the workspaces config
+        if (addToConfig.length > 0) {
+            let workspaces = workspacesConfig;
+            // if the original workspaces config is a string, we'll need
+            // to convert it to an array in order to append the recently
+            // added workspaces
+            if (typeof workspacesConfig === 'string') {
+                workspaces = [workspacesConfig, ...addToConfig];
+            }
+            else if (Array.isArray(workspacesConfig)) {
+                // if the original workspaces config is an array, we simply
+                // append the missing items to it
+                workspaces = [...workspacesConfig, ...addToConfig];
+            }
+            else {
+                // otherwise we assume it's an Record<string, string[]> object
+                // and we'll add the new workspaces to the `packages` keys
+                workspaces = (workspacesConfig ?? {});
+                // if the `packages` key is not being used
+                if (!workspaces.packages) {
+                    workspaces.packages = addToConfig;
+                }
+                else {
+                    // if the `packages` key is defined as a string, we
+                    // convert it to an array to append the new items
+                    if (typeof workspaces.packages === 'string') {
+                        workspaces.packages = [
+                            workspaces.packages,
+                            ...addToConfig,
+                        ];
+                    }
+                    else {
+                        // if it is, we simply append the new workspaces
+                        workspaces.packages = [
+                            ...workspaces.packages,
+                            ...addToConfig,
+                        ];
+                    }
+                }
+            }
+            // finally, we add the new workspaces to the config file
+            save('workspaces', workspaces);
+        }
+        return results;
+    }
+    return init({ cwd: process.cwd() });
+};

package/dist/commands/install/reporter.d.ts

@@ -0,0 +1,10 @@
+import { ViewClass } from '../../view.ts';
+import type { InstallResult } from '../install.ts';
+export declare class InstallReporter extends ViewClass {
+    #private;
+    start(): void;
+    done(_result: InstallResult, { time }: {
+        time: number;
+    }): Promise<undefined>;
+    error(err: unknown): void;
+}

package/dist/commands/install/reporter.js

@@ -0,0 +1,93 @@
+import { emitter } from '@vltpkg/output';
+import { Box, render, Text } from 'ink';
+import Spinner from 'ink-spinner';
+import { createElement as $, Fragment, useEffect, useState, } from 'react';
+import { ViewClass } from "../../view.js";
+import { asError } from '@vltpkg/types';
+const labels = {
+    build: 'resolving dependencies',
+    actual: '',
+    reify: 'extracting files',
+};
+const GraphStep = ({ text, step }) => {
+    if (step.state === 'waiting') {
+        return $(Text, { color: 'gray' }, text);
+    }
+    if (step.state === 'in_progress') {
+        return $(Text, { color: 'yellow' }, text + ' ', $(Spinner, { type: 'dots' }));
+    }
+    return $(Text, { color: 'green' }, text, ' ✓');
+};
+const App = ({ trailer }) => {
+    const [requests, setRequests] = useState(0);
+    const [cacheHit, setCacheHit] = useState(0);
+    const [steps, setSteps] = useState({
+        build: {
+            state: 'waiting',
+        },
+        actual: {
+            state: 'waiting',
+        },
+        reify: {
+            state: 'waiting',
+        },
+    });
+    useEffect(() => {
+        const updateRequests = ({ state }) => {
+            if (state === 'start') {
+                setRequests(p => p + 1);
+            }
+            else if (state === 'cache' || state === 'stale') {
+                setCacheHit(p => p + 1);
+            }
+        };
+        emitter.on('request', updateRequests);
+        return () => emitter.off('request', updateRequests);
+    }, []);
+    useEffect(() => {
+        const update = ({ step, state }) => {
+            setSteps(p => ({
+                ...p,
+                [step]: {
+                    ...p[step],
+                    state: state === 'start' ? 'in_progress' : 'completed',
+                },
+            }));
+        };
+        emitter.on('graphStep', update);
+        return () => emitter.off('graphStep', update);
+    }, []);
+    return $(Fragment, null, $(Box, null, ...['build', 'actual', 'reify'].map((step, idx, list) => {
+        const separator = idx === list.length - 1 ? '' : ' > ';
+        const label = labels[step];
+        if (!label)
+            return null;
+        return $(Text, { key: step }, $(GraphStep, { text: label, step: steps[step] }), $(Text, { color: 'gray' }, separator));
+    })), cacheHit > 0 ?
+        $(Text, null, `${cacheHit} cache hit${cacheHit > 1 ? 's' : ''}`)
+        : null, requests > 0 ?
+        $(Text, null, `${requests} request${requests > 1 ? 's' : ''}`)
+        : null, trailer ? $(Text, null, trailer) : null);
+};
+export class InstallReporter extends ViewClass {
+    #instance = null;
+    start() {
+        this.#instance = render($(App));
+    }
+    async done(_result, { time }) {
+        let out = `Done in ${time}ms`;
+        // prints a very complete message explaining users the next steps
+        // in case there are packages to be built
+        if (_result.buildQueue?.length) {
+            out += `\n\n📦 ${_result.buildQueue.length} packages have install scripts defined & were not fully built\n`;
+            out += '🔎 Run `vlt query :scripts` to list them\n';
+            out +=
+                '🔨 Run `vlt build` to run all required scripts to build installed packages.\n';
+        }
+        this.#instance?.rerender($(App, { trailer: out }));
+        return undefined;
+    }
+    error(err) {
+        this.#instance?.unmount(asError(err));
+    }
+}

package/dist/commands/install.d.ts

@@ -0,0 +1,27 @@
+import { InstallReporter } from './install/reporter.ts';
+import type { DepID } from '@vltpkg/dep-id';
+import type { 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.
+ */
+export type InstallResult = {
+    /**
+     * A queue of package IDs that need to be built after the install is complete.
+     */
+    buildQueue?: DepID[];
+    /**
+     * The resulting graph structure at the end of an install.
+     */
+    graph: Graph;
+};
+export declare const usage: CommandUsage;
+export declare const views: {
+    readonly json: (i: InstallResult) => {
+        graph: import("@vltpkg/graph").LockfileData;
+        buildQueue?: DepID[] | undefined;
+        message?: string | undefined;
+    };
+    readonly human: typeof InstallReporter;
+};
+export declare const command: CommandFn<InstallResult>;

package/dist/commands/install.js

@@ -0,0 +1,80 @@
+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";
+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 => ({
+        ...(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),
+        graph: i.graph.toJSON(),
+    }),
+    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 { buildQueue, graph } = await install({
+        ...conf.options,
+        frozenLockfile,
+        expectLockfile,
+        allowScripts,
+        lockfileOnly,
+    }, add);
+    return { buildQueue, graph };
+};

package/dist/commands/list.d.ts

@@ -0,0 +1,17 @@
+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 & {
+    queryString: string;
+};
+export declare const views: {
+    readonly json: typeof jsonOutput;
+    readonly mermaid: typeof mermaidOutput;
+    readonly human: typeof humanReadableOutput;
+    readonly count: (result: ListResult) => number;
+    readonly svg: typeof MermaidImageView;
+    readonly png: typeof MermaidImageView;
+};
+export declare const command: CommandFn<ListResult>;

package/dist/commands/list.js

@@ -0,0 +1,197 @@
+import { actual, asNode, humanReadableOutput, jsonOutput, mermaidOutput, GraphModifier, } from '@vltpkg/graph';
+import { Query } from '@vltpkg/query';
+import { SecurityArchive } from '@vltpkg/security-archive';
+import { error } from '@vltpkg/error-cause';
+import { commandUsage } from "../config/usage.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 | 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.
+
+      Package names provided as positional arguments will be used to filter
+      the results to show only dependencies with those names.
+
+      The --scope and --target options accepts DSS query selectors to filter
+      packages. Using --scope, you can specify which packages to treat as the
+      top-level items in the output graph. The --target option allows you to
+      filter what dependencies to include in the output. Using both options
+      allows you to render subgraphs of the dependency graph.
+
+      Defaults to listing direct dependencies of a project and any configured
+      workspace.`,
+    examples: {
+        '': {
+            description: 'List direct dependencies of the current project / workspace',
+        },
+        'foo bar baz': {
+            description: `List all dependencies named 'foo', 'bar', or 'baz'`,
+        },
+        '--scope=":root > #dependency-name"': {
+            description: 'Defines a direct dependency as the output top-level scope',
+        },
+        '--target="*"': {
+            description: 'List all dependencies using a query selector',
+        },
+        '--target=":workspace > *:peer"': {
+            description: 'List all peer dependencies of all workspaces',
+        },
+    },
+    options: {
+        scope: {
+            value: '<query>',
+            description: 'Query selector to select top-level packages using the DSS query language syntax.',
+        },
+        target: {
+            value: '<query>',
+            description: 'Query selector to filter packages using the DSS query language syntax.',
+        },
+        view: {
+            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.',
+        },
+    },
+});
+export const views = {
+    json: jsonOutput,
+    mermaid: mermaidOutput,
+    human: humanReadableOutput,
+    count: (result) => result.edges.length,
+    svg: MermaidImageView,
+    png: MermaidImageView,
+};
+export const command = async (conf) => {
+    const modifiers = GraphModifier.maybeLoad(conf.options);
+    const monorepo = conf.options.monorepo;
+    const mainManifest = conf.options.packageJson.maybeRead(conf.options.projectRoot);
+    let graph;
+    let securityArchive;
+    // optionally load the cwd graph if we found a package.json file
+    if (mainManifest) {
+        graph = actual.load({
+            ...conf.options,
+            mainManifest,
+            modifiers,
+            monorepo,
+            loadManifests: true,
+        });
+        securityArchive = await SecurityArchive.start({
+            nodes: [...graph.nodes.values()],
+        });
+    }
+    // Validate positional arguments - only allow package names, not direct queries
+    for (const arg of conf.positionals) {
+        if (!/^[@\w-]/.test(arg)) {
+            throw error(`Direct queries are not supported as positional arguments. Use package names only.`, {
+                code: 'EUSAGE',
+                cause: `Argument '${arg}' appears to be a query syntax. Only package names are allowed as positional arguments.`,
+            });
+        }
+    }
+    // retrieve default values and set up host contexts
+    const positionalQueryString = conf.positionals
+        .map(k => `#${k.replace(/\//, '\\/')}`)
+        .join(', ');
+    const targetQueryString = conf.get('target');
+    const scopeQueryString = conf.get('scope');
+    const queryString = targetQueryString || positionalQueryString;
+    const projectQueryString = ':workspace, :project > *';
+    const selectImporters = [];
+    const hostContexts = await createHostContextsMap(conf);
+    const importers = new Set();
+    const scopeIDs = [];
+    // handle --scope option to add scope nodes as importers
+    let scopeNodes;
+    if (scopeQueryString) {
+        // run scope query to get all matching nodes
+        /* c8 ignore start */
+        const edges = graph?.edges ?? new Set();
+        const nodes = graph?.nodes ?
+            new Set(graph.nodes.values())
+            : new Set();
+        const importers = graph?.importers ?? new Set();
+        /* c8 ignore stop */
+        const scopeQuery = new Query({
+            nodes,
+            edges,
+            importers,
+            securityArchive,
+            hostContexts,
+        });
+        const { nodes: resultNodes } = await scopeQuery.search(scopeQueryString, {
+            signal: new AbortController().signal,
+        });
+        scopeNodes = resultNodes;
+    }
+    if (scopeQueryString && scopeNodes) {
+        // Add all scope nodes to importers Set (treat them as top-level items)
+        for (const queryNode of scopeNodes) {
+            importers.add(asNode(queryNode));
+        }
+    }
+    else if ('workspace' in conf.values) {
+        // if in a workspace environment, select only the specified
+        // workspaces as top-level items
+        if (monorepo && graph) {
+            for (const workspace of monorepo.filter(conf.values)) {
+                const w = graph.nodes.get(workspace.id);
+                if (w) {
+                    importers.add(w);
+                    selectImporters.push(`[name="${w.name}"]`);
+                    selectImporters.push(`[name="${w.name}"] > *`);
+                    scopeIDs.push(workspace.id);
+                }
+            }
+        }
+    }
+    // build a default query string to use in the target search
+    const selectImportersQueryString = selectImporters.join(', ');
+    const defaultProjectQueryString = (graph &&
+        selectImporters.length &&
+        selectImporters.length < graph.importers.size) ?
+        selectImportersQueryString
+        : projectQueryString;
+    const defaultLocalScopeQueryString = ':host(local) :root > *';
+    // retrieve the selected nodes and edges
+    /* c8 ignore start */
+    const edges_ = graph?.edges ?? new Set();
+    const nodes_ = graph?.nodes ?
+        new Set(graph.nodes.values())
+        : new Set();
+    const importers_ = importers.size === 0 && graph ?
+        new Set([graph.mainImporter])
+        : importers;
+    /* c8 ignore stop */
+    const q = new Query({
+        nodes: nodes_,
+        edges: edges_,
+        importers: importers_,
+        securityArchive,
+        hostContexts,
+    });
+    const query = queryString ||
+        /* c8 ignore next */
+        (graph ? defaultProjectQueryString : defaultLocalScopeQueryString);
+    const { edges, nodes, importers: queryResultImporters, } = await q.search(query, {
+        signal: new AbortController().signal,
+        scopeIDs: scopeIDs.length > 0 ? scopeIDs : undefined,
+    });
+    return {
+        importers: importers.size === 0 ?
+            new Set(queryResultImporters)
+            : importers,
+        edges,
+        nodes,
+        highlightSelection: !!(targetQueryString || positionalQueryString),
+        queryString: queryString ||
+            (graph ?
+                /* c8 ignore next 2 */
+                defaultProjectQueryString
+                : defaultLocalScopeQueryString),
+    };
+};

package/dist/commands/login.d.ts

@@ -0,0 +1,3 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const usage: CommandUsage;
+export declare const command: CommandFn<void>;

package/dist/commands/login.js

@@ -0,0 +1,22 @@
+import { RegistryClient } from '@vltpkg/registry-client';
+import { commandUsage } from "../config/usage.js";
+export const usage = () => commandUsage({
+    command: 'login',
+    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);
+};

package/dist/commands/logout.d.ts

@@ -0,0 +1,3 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const usage: CommandUsage;
+export declare const command: CommandFn<void>;

package/dist/commands/logout.js

@@ -0,0 +1,22 @@
+import { RegistryClient } from '@vltpkg/registry-client';
+import { commandUsage } from "../config/usage.js";
+export const usage = () => commandUsage({
+    command: 'logout',
+    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);
+};

package/dist/commands/pack.d.ts

@@ -0,0 +1,31 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+import type { LoadedConfig } from '../config/index.ts';
+export declare const usage: CommandUsage;
+export type CommandResultSingle = {
+    id: string;
+    name: string;
+    version: string;
+    filename: string;
+    files: string[];
+    size: number;
+    unpackedSize: number;
+    shasum?: string;
+    integrity?: string;
+};
+export type CommandResult = CommandResultSingle | CommandResultSingle[];
+export declare const views: {
+    readonly human: (results: CommandResult) => string;
+    readonly json: (r: CommandResult) => CommandResult;
+};
+export declare const command: CommandFn<CommandResult>;
+export declare const commandSingle: (location: string, conf: LoadedConfig) => Promise<{
+    id: string;
+    name: string;
+    version: string;
+    filename: string;
+    files: string[];
+    size: number;
+    unpackedSize: number;
+    shasum: string | undefined;
+    integrity: string | undefined;
+}>;