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

package/dist/commands/access.d.ts

@@ -0,0 +1,22 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const usage: CommandUsage;
+export type AccessResult = {
+    package: string;
+    access: string;
+} | {
+    packages: Record<string, string>;
+} | {
+    granted: {
+        team: string;
+        permissions: string;
+    };
+} | {
+    revoked: {
+        team: string;
+    };
+};
+export declare const views: {
+    readonly human: (result: AccessResult) => string;
+    readonly json: (r: AccessResult) => AccessResult;
+};
+export declare const command: CommandFn<AccessResult>;

package/dist/commands/access.js

@@ -0,0 +1,246 @@
+import { error } from '@vltpkg/error-cause';
+import { RegistryClient } from '@vltpkg/registry-client';
+import { commandUsage } from "../config/usage.js";
+export const usage = () => commandUsage({
+    command: 'access',
+    usage: '<command> [<args>]',
+    description: `Set or get access levels for published packages
+                  and manage team-based package permissions.`,
+    subcommands: {
+        'list packages': {
+            usage: '[<scope|user|org>]',
+            description: 'List packages with access info for a scope, user, or org.',
+        },
+        'get status': {
+            usage: '<package>',
+            description: 'Get the access/visibility status of a package.',
+        },
+        'set status': {
+            usage: '<package>',
+            description: `Set the access/visibility of a package. Use --access to specify the level.`,
+        },
+        grant: {
+            usage: '<read-only|read-write> <scope:team> [<package>]',
+            description: 'Grant access to a scope:team for a package.',
+        },
+        revoke: {
+            usage: '<scope:team> [<package>]',
+            description: 'Revoke access from a scope:team for a package.',
+        },
+    },
+    options: {
+        registry: {
+            value: '<url>',
+            description: 'Registry URL to manage access on.',
+        },
+        otp: {
+            description: 'Provide an OTP for access changes.',
+            value: '<otp>',
+        },
+    },
+});
+export const views = {
+    human: (result) => {
+        if ('packages' in result) {
+            const entries = Object.entries(result.packages);
+            if (entries.length === 0)
+                return 'No packages found.';
+            return entries
+                .map(([name, access]) => `${name}: ${access}`)
+                .join('\n');
+        }
+        if ('granted' in result) {
+            return `Granted ${result.granted.permissions} access to ${result.granted.team}.`;
+        }
+        if ('revoked' in result) {
+            return `Revoked access from ${result.revoked.team}.`;
+        }
+        return `${result.package}: ${result.access}`;
+    },
+    json: (r) => r,
+};
+export const command = async (conf) => {
+    const [sub, ...args] = conf.positionals;
+    switch (sub) {
+        case 'list':
+            return listPackages(conf, args);
+        case 'get':
+            return getStatus(conf, args);
+        case 'set':
+            return setStatus(conf, args);
+        case 'grant':
+            return grant(conf, args);
+        case 'revoke':
+            return revoke(conf, args);
+        default: {
+            throw error('Invalid access subcommand', {
+                found: sub,
+                validOptions: ['list', 'get', 'set', 'grant', 'revoke'],
+                code: 'EUSAGE',
+            });
+        }
+    }
+};
+const encodePkgName = (name) => name.startsWith('@') ?
+    `@${encodeURIComponent(name.slice(1))}`
+    : encodeURIComponent(name);
+const listPackages = async (conf, args) => {
+    const [keyword, entity] = args;
+    if (keyword !== 'packages') {
+        throw error('Expected `list packages [<scope|user|org>]`', {
+            found: keyword,
+            code: 'EUSAGE',
+        });
+    }
+    const rc = new RegistryClient(conf.options);
+    const registryUrl = new URL(conf.options.registry);
+    // Determine who to list for — use entity arg or fall back to scope from package.json
+    const scope = entity ?? getDefaultScope(conf);
+    const url = new URL(`-/org/${encodeURIComponent(scope)}/package`, registryUrl);
+    const response = await rc.request(url, { useCache: false });
+    const data = response.json();
+    return { packages: data };
+};
+const getStatus = async (conf, args) => {
+    const [keyword, pkg] = args;
+    if (keyword !== 'status') {
+        throw error('Expected `get status <package>`', {
+            found: keyword,
+            code: 'EUSAGE',
+        });
+    }
+    if (!pkg) {
+        throw error('Package name is required for `get status`', {
+            code: 'EUSAGE',
+        });
+    }
+    const rc = new RegistryClient(conf.options);
+    const registryUrl = new URL(conf.options.registry);
+    const url = new URL(`-/package/${encodePkgName(pkg)}/access`, registryUrl);
+    const response = await rc.request(url, { useCache: false });
+    const data = response.json();
+    return { package: pkg, access: data.access };
+};
+const setStatus = async (conf, args) => {
+    // vlt access set status=<public|restricted> <package>
+    const [statusArg, pkg] = args;
+    if (!statusArg?.startsWith('status=')) {
+        throw error('Expected `set status=<public|restricted> <package>`', { found: statusArg, code: 'EUSAGE' });
+    }
+    const accessLevel = statusArg.slice('status='.length);
+    if (accessLevel !== 'public' && accessLevel !== 'restricted') {
+        throw error('Access level must be `public` or `restricted`', {
+            found: accessLevel,
+            validOptions: ['public', 'restricted'],
+            code: 'EUSAGE',
+        });
+    }
+    if (!pkg) {
+        throw error('Package name is required for `set status`', {
+            code: 'EUSAGE',
+        });
+    }
+    const rc = new RegistryClient(conf.options);
+    const registryUrl = new URL(conf.options.registry);
+    const url = new URL(`-/package/${encodePkgName(pkg)}/access`, registryUrl);
+    await rc.request(url, {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ access: accessLevel }),
+        otp: conf.options.otp,
+        useCache: false,
+    });
+    return { package: pkg, access: accessLevel };
+};
+const grant = async (conf, args) => {
+    // vlt access grant <read-only|read-write> <scope:team> [<package>]
+    const [permissions, scopeTeam, pkg] = args;
+    if (permissions !== 'read-only' && permissions !== 'read-write') {
+        throw error('Permissions must be `read-only` or `read-write`', {
+            found: permissions,
+            validOptions: ['read-only', 'read-write'],
+            code: 'EUSAGE',
+        });
+    }
+    if (!scopeTeam?.includes(':')) {
+        throw error('Team must be in the format `<scope>:<team>`', {
+            found: scopeTeam,
+            code: 'EUSAGE',
+        });
+    }
+    const [scope, team] = scopeTeam.split(':');
+    if (!scope || !team) {
+        throw error('Team must be in the format `<scope>:<team>`', {
+            found: scopeTeam,
+            code: 'EUSAGE',
+        });
+    }
+    const pkgName = pkg ?? getDefaultPkgName(conf);
+    const rc = new RegistryClient(conf.options);
+    const registryUrl = new URL(conf.options.registry);
+    const url = new URL(`-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}/package`, registryUrl);
+    await rc.request(url, {
+        method: 'PUT',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            package: pkgName,
+            permissions,
+        }),
+        otp: conf.options.otp,
+        useCache: false,
+    });
+    return {
+        granted: {
+            team: `${scope}:${team}`,
+            permissions,
+        },
+    };
+};
+const revoke = async (conf, args) => {
+    // vlt access revoke <scope:team> [<package>]
+    const [scopeTeam, pkg] = args;
+    if (!scopeTeam?.includes(':')) {
+        throw error('Team must be in the format `<scope>:<team>`', {
+            found: scopeTeam,
+            code: 'EUSAGE',
+        });
+    }
+    const [scope, team] = scopeTeam.split(':');
+    if (!scope || !team) {
+        throw error('Team must be in the format `<scope>:<team>`', {
+            found: scopeTeam,
+            code: 'EUSAGE',
+        });
+    }
+    const pkgName = pkg ?? getDefaultPkgName(conf);
+    const rc = new RegistryClient(conf.options);
+    const registryUrl = new URL(conf.options.registry);
+    const url = new URL(`-/team/${encodeURIComponent(scope)}/${encodeURIComponent(team)}/package`, registryUrl);
+    await rc.request(url, {
+        method: 'DELETE',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ package: pkgName }),
+        otp: conf.options.otp,
+        useCache: false,
+    });
+    return {
+        revoked: {
+            team: `${scope}:${team}`,
+        },
+    };
+};
+const getDefaultScope = (conf) => {
+    const name = conf.options.packageJson.maybeRead(conf.projectRoot)?.name;
+    if (name?.startsWith('@')) {
+        const scope = name.split('/')[0];
+        if (scope)
+            return scope;
+    }
+    throw error('Could not determine scope. Provide a scope, user, or org.', { code: 'EUSAGE' });
+};
+const getDefaultPkgName = (conf) => {
+    const name = conf.options.packageJson.maybeRead(conf.projectRoot)?.name;
+    if (name)
+        return name;
+    throw error('Could not determine package name. Provide a package name or run from a package directory.', { code: 'EUSAGE' });
+};

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/{esm/commands → commands}/build.d.ts

@@ -22,4 +22,3 @@ export declare const usage: CommandUsage;
  * lifecycle scripts and binary linking.
  */
 export declare const command: CommandFn<BuildResult>;
-//# sourceMappingURL=build.d.ts.map

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

@@ -99,4 +99,3 @@ export const command = async (conf) => {
         throw error('Build failed', { cause });
     }
 };
-//# sourceMappingURL=build.js.map

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

@@ -62,4 +62,3 @@ declare const usageDef: {
 export declare const usage: CommandUsage;
 export declare const command: CommandFn<void | CacheMap>;
 export {};
-//# sourceMappingURL=cache.d.ts.map

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

@@ -254,4 +254,3 @@ const add = async (conf, specs, view) => {
     }
     await Promise.all(promises);
 };
-//# sourceMappingURL=cache.js.map

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

@@ -8,4 +8,3 @@ export declare const views: {
     readonly human: typeof InstallReporter;
 };
 export declare const command: CommandFn<CIResult>;
-//# sourceMappingURL=ci.d.ts.map

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

@@ -11,6 +11,15 @@ export const usage = () => commandUsage({
     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(),
@@ -19,8 +28,8 @@ export const views = {
 export const command = async (conf) => {
     const ciOptions = {
         ...conf.options,
-        // allow all scripts by default on ci (unless user specifies a filter)
-        allowScripts: conf.get('allow-scripts') ?? '*',
+        // allow scripts but filter out malware via security archive
+        allowScripts: conf.get('allow-scripts') ?? ':scripts:not(:malware)',
         expectLockfile: true,
         frozenLockfile: true,
         cleanInstall: true,
@@ -29,4 +38,3 @@ export const command = async (conf) => {
     const { graph } = await install(ciOptions);
     return { graph };
 };
-//# sourceMappingURL=ci.js.map

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

@@ -3,4 +3,3 @@ import type { Views } from '../view.ts';
 export declare const views: Views;
 export declare const usage: CommandUsage;
 export declare const command: CommandFn;
-//# sourceMappingURL=config.d.ts.map

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

@@ -18,6 +18,12 @@ export const usage = () => commandUsage({
     command: 'config',
     usage: '[<command>] [<args>]',
     description: 'Get or manipulate vlt configuration values',
+    options: {
+        config: {
+            value: '<all | user | project>',
+            description: 'Specify which configuration to show or operate on.',
+        },
+    },
     subcommands: {
         get: {
             usage: '[<key>] [--config=<all | user | project>]',
@@ -421,4 +427,3 @@ const configLocation = (conf) => {
     const configPath = find(effectiveConfig);
     return configPath;
 };
-//# sourceMappingURL=config.js.map

package/dist/commands/create.d.ts

@@ -0,0 +1,8 @@
+import type { PromptFn } from '@vltpkg/vlx';
+import type { ExecResult } from '../exec-command.ts';
+import type { CommandFn, CommandUsage } from '../index.ts';
+export { views } from '../exec-command.ts';
+export declare const usage: CommandUsage;
+export declare const prettyPath: (path: string) => string;
+export declare const promptFn: PromptFn;
+export declare const command: CommandFn<ExecResult>;

package/dist/commands/create.js

@@ -0,0 +1,102 @@
+import { exec, execFG } from '@vltpkg/run';
+import * as vlx from '@vltpkg/vlx';
+import { homedir } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import { commandUsage } from "../config/usage.js";
+import { ExecCommand } from "../exec-command.js";
+import { styleTextStdout } from "../output.js";
+export { views } from "../exec-command.js";
+export const usage = () => commandUsage({
+    command: 'create',
+    usage: '<initializer> [args...]',
+    description: `Initialize a new project from a template package.
+
+                  Works like \`npm create\` and \`bun create\`, automatically
+                  prepending "create-" to the package name and executing it.
+
+                  For example, \`vlt create react-app my-app\` will fetch and
+                  execute the \`create-react-app\` package with the arguments
+                  \`my-app\`.
+
+                  If a satisfying instance of the create package exists in the
+                  local \`node_modules\` folder, then that will be used.
+
+                  At no point will \`vlt create\` change the locally installed
+                  dependencies. Any installs it performs is done in vlt's XDG
+                  data directory.
+    `,
+    examples: {
+        'react-app my-app': {
+            description: 'Create a new React app using create-react-app',
+        },
+        'vite my-project': {
+            description: 'Create a new Vite project using create-vite',
+        },
+        '@scope/template my-app': {
+            description: 'Create a new project using @scope/create-template',
+        },
+    },
+    options: {
+        'allow-scripts': {
+            value: '<query>',
+            description: 'Filter which packages are allowed to run lifecycle scripts using DSS query syntax.',
+        },
+        yes: {
+            description: 'Skip interactive prompts and accept defaults.',
+        },
+    },
+});
+const HOME = homedir();
+export const prettyPath = (path) => path.startsWith(HOME) ? `~${path.substring(HOME.length)}` : path;
+export const promptFn = async (pkgSpec, path, resolution) => {
+    const response = await createInterface(process.stdin, process.stdout).question(`About to install: ${styleTextStdout(['bgWhiteBright', 'black', 'bold'], String(pkgSpec))}
+from: ${styleTextStdout(['bgWhiteBright', 'black', 'bold'], resolution)}
+into: ${styleTextStdout(['bgWhiteBright', 'black', 'bold'], prettyPath(path))}
+Is this ok? (y) `);
+    process.stdin.pause();
+    return response;
+};
+export const command = async (conf) => {
+    const [initializer, ...args] = conf.positionals;
+    if (!initializer) {
+        throw new Error('Missing required argument: <initializer>\n\nUsage: vlt create <initializer> [args...]');
+    }
+    // Transform the initializer to a create-* package name
+    // e.g., "react-app" -> "create-react-app"
+    // or "@scope/template" -> "@scope/create-template"
+    let packageName;
+    if (initializer.startsWith('@')) {
+        // Handle scoped packages: @scope/name -> @scope/create-name
+        const [scope, name] = initializer.split('/');
+        packageName = name ? `${scope}/create-${name}` : `${scope}/create`;
+    }
+    else {
+        // Handle regular packages: name -> create-name
+        packageName = `create-${initializer}`;
+    }
+    /* c8 ignore start */
+    const allowScripts = conf.get('allow-scripts') ?
+        String(conf.get('allow-scripts'))
+        : ':not(*)';
+    /* c8 ignore stop */
+    const yesFlag = conf.get('yes');
+    // Resolve the create-* package using vlx. We pass the package name as
+    // a synthetic positional so vlx treats it as the command to resolve —
+    // NOT the user's args (like "app"). Without this, vlx would mistake
+    // the first user arg as the executable to spawn.
+    const arg0 = await vlx.resolve([packageName], {
+        ...conf.options,
+        query: undefined,
+        allowScripts,
+    }, yesFlag ? async () => 'y' : promptFn);
+    // Set positionals to the resolved executable and the user's args
+    if (arg0) {
+        conf.positionals = [arg0, ...args];
+    }
+    else {
+        throw new Error(`Could not resolve executable for package "${packageName}"`);
+    }
+    // Execute the create package
+    delete conf.options['script-shell'];
+    return await new ExecCommand(conf, exec, execFG).run();
+};

package/dist/commands/deprecate.d.ts

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