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

package/dist/commands/publish.js

@@ -0,0 +1,282 @@
+import { error } from '@vltpkg/error-cause';
+import { RegistryClient, oidc } from '@vltpkg/registry-client';
+import { run } from '@vltpkg/run';
+import { commandUsage } from "../config/usage.js";
+import { packTarball } from "../pack-tarball.js";
+import assert from 'node:assert';
+import { asError } from '@vltpkg/types';
+import { dirname, resolve } from 'node:path';
+import prettyBytes from 'pretty-bytes';
+import { actual } from '@vltpkg/graph';
+import { Query } from '@vltpkg/query';
+import { createHostContextsMap } from "../query-host-contexts.js";
+import { minimatch } from 'minimatch';
+export const usage = () => commandUsage({
+    command: 'publish',
+    usage: '',
+    description: `Create a tarball from a package and publish it to the configured registry.
+    
+    This command will pack the package in the current directory or specified folder,
+    and then upload it to the configured registry.`,
+    options: {
+        tag: {
+            description: 'Publish the package with the given tag',
+            value: '<tag>',
+        },
+        access: {
+            description: 'Set access level (public or restricted)',
+            value: '<level>',
+        },
+        otp: {
+            description: `Provide an OTP to use when publishing a package.`,
+            value: '<otp>',
+        },
+        'publish-directory': {
+            description: `Directory to use for pack and publish operations instead of the current directory.
+                    The directory must exist and nothing will be copied to it.`,
+            value: '<path>',
+        },
+        'dry-run': {
+            description: 'Show what would be published without actually publishing.',
+        },
+        scope: {
+            value: '<query>',
+            description: 'Filter packages to publish using a DSS query selector.',
+        },
+        workspace: {
+            value: '<path|glob>',
+            description: 'Limit publish targets to matching workspaces.',
+        },
+        'workspace-group': {
+            value: '<name>',
+            description: 'Limit publish targets to workspace groups.',
+        },
+        recursive: {
+            description: 'Publish all workspaces in the monorepo.',
+        },
+    },
+});
+export const views = {
+    human: results => {
+        const item = (r) => {
+            const lines = [
+                `📦 Package: ${r.id}`,
+                `🏷️ Tag: ${r.tag}`,
+                `📡 Registry: ${r.registry}`,
+                `📁 ${r.files.length} Files`,
+                ...r.files.map(f => `  - ${f}`),
+                `📊 Package Size: ${prettyBytes(r.size)}`,
+                `📂 Unpacked Size: ${prettyBytes(r.unpackedSize)}`,
+            ];
+            if (r.shasum)
+                lines.push(`🔒 Shasum: ${r.shasum}`);
+            if (r.integrity)
+                lines.push(`🔐 Integrity: ${r.integrity}`);
+            return lines.join('\n');
+        };
+        return Array.isArray(results) ?
+            results.map(item).join('\n\n')
+            : item(results);
+    },
+    json: r => r,
+};
+export const command = async (conf) => {
+    const { options, projectRoot } = conf;
+    const queryString = conf.get('scope');
+    const paths = conf.get('workspace');
+    const groups = conf.get('workspace-group');
+    const recursive = conf.get('recursive');
+    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));
+        }
+    }
+    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);
+        }
+    }
+    else {
+        single = options.packageJson.find(process.cwd()) ?? projectRoot;
+    }
+    if (single) {
+        return commandSingle(single, conf);
+    }
+    assert(locations.length > 0, error('No workspaces or query results found'));
+    const results = [];
+    for (const location of locations) {
+        results.push(await commandSingle(location, conf));
+    }
+    return results;
+};
+const commandSingle = async (location, conf) => {
+    const manifestPath = conf.options.packageJson.find(location);
+    assert(manifestPath, 'No package.json found');
+    const manifestDir = dirname(manifestPath);
+    const manifest = conf.options.packageJson.read(manifestDir);
+    assert(!manifest.private, error('Package has been marked as private'));
+    const { tag, access, registry, 'dry-run': dry = false, otp, } = conf.options;
+    const registryUrl = new URL(registry);
+    const runOptions = {
+        cwd: manifestDir,
+        projectRoot: conf.projectRoot,
+        packageJson: conf.options.packageJson,
+        manifest,
+        ignoreMissing: true,
+        ignorePrePost: true,
+    };
+    await run({
+        ...runOptions,
+        arg0: 'prepublishOnly',
+    });
+    await run({
+        ...runOptions,
+        arg0: 'prepublish',
+    });
+    await run({
+        ...runOptions,
+        arg0: 'prepack',
+    });
+    await run({
+        ...runOptions,
+        arg0: 'prepare',
+    });
+    // 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, tarballName, tarballData, unpackedSize, files, integrity, shasum, resolvedManifest, } = await packTarball(updatedManifest, manifestDir, conf);
+    await run({
+        ...runOptions,
+        arg0: 'postpack',
+    });
+    await run({
+        ...runOptions,
+        arg0: 'publish',
+    });
+    const publishMetadata = {
+        _id: name,
+        name,
+        description: resolvedManifest.description || '',
+        'dist-tags': {
+            [tag]: version,
+        },
+        versions: {
+            [version]: {
+                ...resolvedManifest,
+                _id: `${name}@${version}`,
+                _nodeVersion: process.versions.node,
+                dist: {
+                    ...resolvedManifest.dist,
+                    integrity,
+                    shasum,
+                    tarball: new URL(`${name}/-/${tarballName}`, registryUrl)
+                        .href,
+                },
+            },
+        },
+        ...(access ? { access } : {}),
+        _attachments: {
+            [tarballName]: {
+                content_type: 'application/octet-stream',
+                data: tarballData.toString('base64'),
+                length: tarballData.length,
+            },
+        },
+    };
+    const rc = new RegistryClient(conf.options);
+    // Attempt OIDC token exchange for CI environments (GitHub Actions, GitLab, CircleCI).
+    // This is always optional — failures are silent and won't affect local publishing.
+    await oidc({
+        packageName: name,
+        registry: registryUrl.href,
+    });
+    const publishUrl = new URL(name.startsWith('@') ? name.replace('/', '%2F') : name, registryUrl);
+    if (!dry) {
+        let response;
+        try {
+            response = await rc.request(publishUrl, {
+                method: 'PUT',
+                headers: {
+                    'content-type': 'application/json',
+                    // These control what type of OTP auth flow is used
+                    'npm-auth-type': 'web',
+                    'npm-command': 'publish',
+                },
+                body: JSON.stringify(publishMetadata),
+                otp,
+            });
+        }
+        catch (err) {
+            throw error('Failed to publish package', {
+                cause: asError(err),
+            });
+        }
+        if (response.statusCode !== 200 && response.statusCode !== 201) {
+            let extraMsg = '';
+            // special case 404 errors to provide a better hint to the user
+            if (response.statusCode === 404) {
+                extraMsg =
+                    ".\n⚠️ Make sure you're logged in and have access to publish the package.";
+            }
+            throw error(`Failed to publish package${extraMsg}`, {
+                url: publishUrl,
+                response,
+            });
+        }
+    }
+    await run({
+        ...runOptions,
+        arg0: 'postpublish',
+    });
+    return {
+        id: `${name}@${version}`,
+        name,
+        version,
+        tag,
+        ...(access ? { access } : {}),
+        registry: registryUrl.origin,
+        integrity,
+        shasum,
+        size: tarballData.length,
+        unpackedSize,
+        files,
+    };
+};

package/dist/commands/query.d.ts

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

package/dist/commands/query.js

@@ -0,0 +1,216 @@
+import { actual, asNode, humanReadableOutput, jsonOutput, mermaidOutput, GraphModifier, } from '@vltpkg/graph';
+import { error } from '@vltpkg/error-cause';
+import { Query } from '@vltpkg/query';
+import { createDiffFilesProvider } from "../query-diff-files.js";
+import { SecurityArchive } from '@vltpkg/security-archive';
+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: 'query',
+    usage: [
+        '',
+        '<query> --view=<human | json | mermaid | svg | png | count>',
+        '<query> --expect-results=<comparison string>',
+        '--target=<query> --view=<human | json | mermaid | svg | png | count>',
+    ],
+    description: `List installed dependencies matching the provided query.
+
+      The vlt Dependency Selector Syntax is a CSS-like query language that
+      allows you to filter installed dependencies using a variety of metadata
+      in the form of CSS-like attributes, pseudo selectors & combinators.
+
+      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 can be used as
+      an alternative to positional arguments, it 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 all dependencies of the project root and workspaces.`,
+    examples: {
+        [`'#foo'`]: {
+            description: 'Query dependencies declared as "foo"',
+        },
+        [`'*:workspace > *:peer'`]: {
+            description: 'Query all peer dependencies of workspaces',
+        },
+        [`':project > *:attr(scripts, [build])'`]: {
+            description: 'Query all direct project dependencies with a "build" script',
+        },
+        [`'[name^="@vltpkg"]'`]: {
+            description: 'Query packages with names starting with "@vltpkg"',
+        },
+        [`'*:license(copyleft) --expect-results=0'`]: {
+            description: 'Errors if a copyleft licensed package is found',
+        },
+        '--scope=":root > #dependency-name"': {
+            description: 'Defines a direct dependency as the output top-level scope',
+        },
+        [`'--target="*"'`]: {
+            description: 'Query all dependencies using the target option',
+        },
+        [`'--target=":workspace > *:peer"'`]: {
+            description: 'Query all peer dependencies of workspaces using target option',
+        },
+    },
+    options: {
+        'expect-results': {
+            value: '[number | string]',
+            description: 'Sets an expected number of resulting items. Errors if the number of resulting items does not match the set value. Accepts a specific numeric value or a string value starting with either ">", "<", ">=" or "<=" followed by a numeric value to be compared.',
+        },
+        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 DSS 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.',
+        },
+    },
+});
+const validateExpectedResult = (conf, edges) => {
+    const expectResults = conf.values['expect-results'];
+    if (expectResults?.startsWith('>=')) {
+        return edges.length >= parseInt(expectResults.slice(2).trim(), 10);
+    }
+    else if (expectResults?.startsWith('<=')) {
+        return edges.length <= parseInt(expectResults.slice(2).trim(), 10);
+    }
+    else if (expectResults?.startsWith('>')) {
+        return edges.length > parseInt(expectResults.slice(1).trim(), 10);
+    }
+    else if (expectResults?.startsWith('<')) {
+        return edges.length < parseInt(expectResults.slice(1).trim(), 10);
+    }
+    else if (expectResults) {
+        return edges.length === parseInt(expectResults.trim(), 10);
+    }
+    return true;
+};
+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()],
+        });
+    }
+    // retrieve default values and set up host contexts
+    const defaultProjectQueryString = '*';
+    const defaultLocalScopeQueryString = ':host(local) *';
+    const positionalQueryString = conf.positionals[0];
+    const targetQueryString = conf.get('target');
+    const scopeQueryString = conf.get('scope');
+    const queryString = targetQueryString || positionalQueryString;
+    const hostContexts = await createHostContextsMap(conf);
+    const diffFiles = createDiffFilesProvider(conf.options.projectRoot);
+    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({
+            edges,
+            nodes,
+            importers,
+            securityArchive,
+            hostContexts,
+            diffFiles,
+        });
+        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);
+                    scopeIDs.push(workspace.id);
+                }
+            }
+        }
+    }
+    // retrieve the selected nodes and edges
+    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;
+    const q = new Query({
+        edges: edges_,
+        nodes: nodes_,
+        importers: importers_,
+        securityArchive,
+        hostContexts,
+        diffFiles,
+    });
+    const query = queryString ||
+        (graph ? defaultProjectQueryString : defaultLocalScopeQueryString);
+    const { edges, nodes, importers: queryResultImporters, } = await q.search(query, {
+        signal: new AbortController().signal,
+        scopeIDs: scopeIDs.length > 0 ? scopeIDs : undefined,
+    });
+    if (!validateExpectedResult(conf, edges)) {
+        throw error('Unexpected number of items', {
+            found: edges.length,
+            wanted: conf.values['expect-results'],
+        });
+    }
+    return {
+        importers: importers.size === 0 ?
+            new Set(queryResultImporters)
+            : importers,
+        edges,
+        nodes,
+        highlightSelection: !!(targetQueryString || positionalQueryString),
+        queryString: queryString ||
+            (graph ?
+                defaultProjectQueryString
+                : defaultLocalScopeQueryString),
+    };
+};

package/dist/commands/repo.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/repo.js

@@ -0,0 +1,157 @@
+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: 'repo',
+    usage: ['[<spec>]', '[--target=<query>]'],
+    description: `Open repository page for a package in a web browser.
+                  Reads repository 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 repo for the current package (reads local package.json)',
+        },
+        'abbrev@2.0.0': {
+            description: 'Open repo for a specific package version',
+        },
+        '--target=":root > *"': {
+            description: 'List repository URLs for all direct dependencies',
+        },
+    },
+});
+export const views = {
+    human: r => {
+        if (Array.isArray(r)) {
+            let msg = 'Multiple package repositories found:\n';
+            msg += r.map(item => `• ${item.name}: ${item.url}`).join('\n');
+            return msg;
+        }
+        return '';
+    },
+    json: r => r,
+};
+const getUrlFromManifest = (manifest) => {
+    const { name, repository, homepage } = manifest;
+    if (!name) {
+        throw error('No package name found');
+    }
+    let url;
+    // Check repository field first
+    if (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?.browse && typeof info.browse === 'function') {
+                url = info.browse();
+            }
+            else {
+                // Use the raw URL if hosted-git-info can't parse it
+                url = repoUrl.replace(/^git\+/, '');
+            }
+        }
+    }
+    // Fall back to homepage
+    if (!url && homepage) {
+        url = homepage;
+    }
+    // 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 };
+};