@vltpkg/cli-sdk 1.0.0-rc.26 → 1.0.0-rc.29

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/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>;

package/dist/commands/deprecate.js

@@ -0,0 +1,139 @@
+import { error } from '@vltpkg/error-cause';
+import { PackageInfoClient } from '@vltpkg/package-info';
+import { RegistryClient } from '@vltpkg/registry-client';
+import { Spec } from '@vltpkg/spec';
+import { satisfies } from '@vltpkg/semver';
+import { asError } from '@vltpkg/types';
+import { commandUsage } from "../config/usage.js";
+export const usage = () => commandUsage({
+    command: 'deprecate',
+    usage: '<pkg>[@<version>] <message>',
+    description: `Update the npm registry entry for a package, providing a
+                  deprecation warning to all who attempt to install it.
+
+                  It works on version ranges as well as specific versions,
+                  so you can un-deprecate a previously deprecated package by
+                  specifying the version range with an empty string as the
+                  message.`,
+    examples: {
+        'my-package "this package is no longer maintained"': {
+            description: 'Deprecate all versions of a package',
+        },
+        'my-package@"<0.2.0" "critical bug, please update"': {
+            description: 'Deprecate specific versions',
+        },
+        'my-package ""': {
+            description: 'Un-deprecate a package',
+        },
+    },
+    options: {
+        registry: {
+            value: '<url>',
+            description: 'The registry to update.',
+        },
+        otp: {
+            description: `Provide an OTP to use when deprecating a package.`,
+            value: '<otp>',
+        },
+    },
+});
+export const views = {
+    human: result => {
+        if (result.message === '') {
+            return `✅ Un-deprecated ${result.name}@${result.version} (${result.versions.length} version${result.versions.length === 1 ? '' : 's'})`;
+        }
+        return `⚠️ Deprecated ${result.name}@${result.version} (${result.versions.length} version${result.versions.length === 1 ? '' : 's'}): ${result.message}`;
+    },
+    json: r => r,
+};
+export const command = async (conf) => {
+    const specArg = conf.positionals[0];
+    const message = conf.positionals[1];
+    if (!specArg) {
+        throw error('deprecate requires a package spec and message argument', {
+            code: 'EUSAGE',
+        });
+    }
+    if (message === undefined) {
+        throw error('deprecate requires a message argument', {
+            code: 'EUSAGE',
+        });
+    }
+    const spec = Spec.parseArgs(specArg, conf.options);
+    const { name } = spec;
+    if (!name || name === '(unknown)') {
+        throw error('could not determine package name from spec', {
+            found: specArg,
+        });
+    }
+    const { registry, otp } = conf.options;
+    const registryUrl = new URL(registry);
+    // Fetch the current packument
+    const pic = new PackageInfoClient(conf.options);
+    const packument = await pic.packument(spec);
+    // Determine which versions match the spec
+    const versionRange = spec.bareSpec;
+    const matchedVersions = [];
+    for (const version of Object.keys(packument.versions)) {
+        if (!versionRange || satisfies(version, versionRange)) {
+            matchedVersions.push(version);
+        }
+    }
+    if (matchedVersions.length === 0) {
+        throw error('no versions found matching the spec', {
+            found: specArg,
+            wanted: Object.keys(packument.versions),
+        });
+    }
+    // Build the update payload with deprecated field set on matched versions
+    const versions = {};
+    for (const version of matchedVersions) {
+        const manifest = packument.versions[version];
+        /* c8 ignore next */
+        if (!manifest)
+            continue;
+        versions[version] = {
+            ...manifest,
+            ...(message === '' ?
+                { deprecated: undefined }
+                : { deprecated: message }),
+        };
+    }
+    const body = {
+        _id: name,
+        name,
+        versions,
+    };
+    const rc = new RegistryClient(conf.options);
+    const packageUrl = new URL(name.startsWith('@') ? name.replace('/', '%2F') : name, registryUrl);
+    let response;
+    try {
+        response = await rc.request(packageUrl, {
+            method: 'PUT',
+            headers: {
+                'content-type': 'application/json',
+                'npm-auth-type': 'web',
+                'npm-command': 'deprecate',
+            },
+            body: JSON.stringify(body),
+            otp,
+        });
+    }
+    catch (err) {
+        throw error('failed to update deprecation status', {
+            cause: asError(err),
+        });
+    }
+    if (response.statusCode !== 200 && response.statusCode !== 201) {
+        throw error('failed to update deprecation status', {
+            url: packageUrl,
+            response,
+        });
+    }
+    return {
+        name,
+        version: versionRange || '*',
+        message,
+        versions: matchedVersions,
+    };
+};

package/dist/commands/dist-tag.d.ts

@@ -0,0 +1,21 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const usage: CommandUsage;
+export type DistTagLsResult = {
+    id: string;
+    tags: Record<string, string>;
+};
+export type DistTagAddResult = {
+    id: string;
+    tag: string;
+    version: string;
+};
+export type DistTagRmResult = {
+    id: string;
+    tag: string;
+};
+export type CommandResult = DistTagLsResult | DistTagAddResult | DistTagRmResult;
+export declare const views: {
+    readonly human: (result: CommandResult) => string;
+    readonly json: (r: CommandResult) => CommandResult;
+};
+export declare const command: CommandFn<CommandResult>;

package/dist/commands/dist-tag.js

@@ -0,0 +1,177 @@
+import { error } from '@vltpkg/error-cause';
+import { RegistryClient } from '@vltpkg/registry-client';
+import { Spec } from '@vltpkg/spec';
+import { commandUsage } from "../config/usage.js";
+export const usage = () => commandUsage({
+    command: 'dist-tag',
+    usage: [
+        'add <pkg>@<version> [<tag>]',
+        'rm <pkg> <tag>',
+        'ls [<pkg>]',
+    ],
+    description: `Manage distribution tags for a package.
+
+    Distribution tags (dist-tags) provide aliases for package versions,
+    allowing users to install specific versions using tag names instead
+    of version numbers. The most common tag is \`latest\`, which is used
+    by default when no tag is specified during install.`,
+    subcommands: {
+        add: {
+            usage: '<pkg>@<version> [<tag>]',
+            description: 'Tag the specified version of a package with the given tag, or "latest" if unspecified.',
+        },
+        rm: {
+            usage: '<pkg> <tag>',
+            description: 'Remove a dist-tag from a package.',
+        },
+        ls: {
+            usage: '[<pkg>]',
+            description: 'List all dist-tags for a package, defaulting to the package in the current directory.',
+        },
+    },
+    options: {
+        registry: {
+            value: '<url>',
+            description: 'Registry URL to manage dist-tags for.',
+        },
+        identity: {
+            value: '<name>',
+            description: 'Identity namespace used to look up auth tokens.',
+        },
+    },
+});
+const isLsResult = (r) => 'tags' in r;
+const isAddResult = (r) => 'version' in r;
+export const views = {
+    human: result => {
+        if (isLsResult(result)) {
+            const entries = Object.entries(result.tags);
+            if (entries.length === 0)
+                return 'No dist-tags found.';
+            return entries
+                .map(([tag, version]) => `${tag}: ${version}`)
+                .join('\n');
+        }
+        if (isAddResult(result)) {
+            return `+${result.tag}: ${result.id}@${result.version}`;
+        }
+        return `-${result.tag}: ${result.id}`;
+    },
+    json: r => r,
+};
+/**
+ * Build the dist-tags API URL for a package.
+ * Uses the `/-/package/{name}/dist-tags` endpoint.
+ */
+const distTagsUrl = (name, registry, tag) => {
+    const encoded = name.startsWith('@') ? name.replace('/', '%2f') : name;
+    const path = tag ?
+        `-/package/${encoded}/dist-tags/${encodeURIComponent(tag)}`
+        : `-/package/${encoded}/dist-tags`;
+    return new URL(path, registry);
+};
+const readPackageName = (positional, conf) => {
+    if (positional) {
+        const spec = Spec.parseArgs(positional, conf.options);
+        return spec.name;
+    }
+    const manifest = conf.options.packageJson.maybeRead(conf.projectRoot);
+    if (manifest?.name)
+        return manifest.name;
+    throw error('Could not determine package name', {
+        code: 'EUSAGE',
+    });
+};
+export const command = async (conf) => {
+    const [sub, ...args] = conf.positionals;
+    if (!sub) {
+        throw error('dist-tag command requires a subcommand', {
+            code: 'EUSAGE',
+            validOptions: ['add', 'rm', 'remove', 'ls', 'list'],
+        });
+    }
+    const rc = new RegistryClient(conf.options);
+    const registry = conf.options.registry;
+    switch (sub) {
+        case 'add': {
+            const specArg = args[0];
+            if (!specArg) {
+                throw error('dist-tag add requires a package@version argument', {
+                    code: 'EUSAGE',
+                });
+            }
+            const spec = Spec.parseArgs(specArg, conf.options);
+            const name = spec.name;
+            const version = spec.bareSpec;
+            if (!version) {
+                throw error('dist-tag add requires a version in the spec', {
+                    code: 'EUSAGE',
+                    found: specArg,
+                });
+            }
+            const tag = args[1] ?? conf.options.tag;
+            const url = distTagsUrl(name, registry, tag);
+            const response = await rc.request(url, {
+                method: 'PUT',
+                headers: {
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify(version),
+                useCache: false,
+            });
+            if (response.statusCode < 200 || response.statusCode >= 300) {
+                throw error('Failed to add dist-tag', {
+                    url,
+                    response,
+                });
+            }
+            return { id: name, tag, version };
+        }
+        case 'rm':
+        case 'remove': {
+            const pkgArg = args[0];
+            const tag = args[1];
+            if (!pkgArg || !tag) {
+                throw error('dist-tag rm requires a package name and tag', {
+                    code: 'EUSAGE',
+                });
+            }
+            const name = readPackageName(pkgArg, conf);
+            const url = distTagsUrl(name, registry, tag);
+            const response = await rc.request(url, {
+                method: 'DELETE',
+                useCache: false,
+            });
+            if (response.statusCode < 200 || response.statusCode >= 300) {
+                throw error('Failed to remove dist-tag', {
+                    url,
+                    response,
+                });
+            }
+            return { id: name, tag };
+        }
+        case 'ls':
+        case 'list': {
+            const name = readPackageName(args[0], conf);
+            const url = distTagsUrl(name, registry);
+            const response = await rc.request(url, {
+                useCache: false,
+            });
+            if (response.statusCode < 200 || response.statusCode >= 300) {
+                throw error('Failed to list dist-tags', {
+                    url,
+                    response,
+                });
+            }
+            const tags = response.json();
+            return { id: name, tags };
+        }
+        default: {
+            throw error('Invalid dist-tag subcommand', {
+                found: sub,
+                validOptions: ['add', 'rm', 'remove', 'ls', 'list'],
+                code: 'EUSAGE',
+            });
+        }
+    }
+};