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

package/dist/commands/init.js

@@ -2,13 +2,16 @@ import { mkdirSync } from 'node:fs';
 import { relative, resolve } from 'node:path';
 import { minimatch } from 'minimatch';
 import { init } from '@vltpkg/init';
+import { install } from '@vltpkg/graph';
 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.`,
+    description: `Initialize a new project in the current directory.
+                  Creates a package.json, a .gitignore, and installs
+                  dependencies so the project is ready to use immediately.`,
     options: {
         workspace: {
             value: '<path|glob>',
@@ -23,17 +26,20 @@ export const views = {
         // 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}:`);
+                for (const [type, value] of Object.entries(result)) {
+                    output.push(`Wrote ${type} to ${value.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)}`);
+            for (const [type, value] of Object.entries(results)) {
+                if ('data' in value) {
+                    output.push(`Wrote ${type} to ${value.path}:\n\n${JSON.stringify(value.data, null, 2)}`);
+                }
+                else {
+                    output.push(`Wrote ${type} to ${value.path}`);
+                }
             }
         }
         output.push(`\nModify/add properties using \`vlt pkg\`. For example:
@@ -43,6 +49,11 @@ ${JSON.stringify(data, null, 2)}`);
     },
 };
 export const command = async (conf) => {
+    /* c8 ignore start */
+    const allowScripts = conf.get('allow-scripts') ?
+        String(conf.get('allow-scripts'))
+        : ':not(*)';
+    /* c8 ignore stop */
     if (conf.values.workspace?.length) {
         const workspacesConfig = load('workspaces', assertWSConfig);
         const parsedWSConfig = asWSConfig(workspacesConfig ?? {});
@@ -84,7 +95,7 @@ export const command = async (conf) => {
             else {
                 // otherwise we assume it's an Record<string, string[]> object
                 // and we'll add the new workspaces to the `packages` keys
-                workspaces = (workspacesConfig ?? {});
+                workspaces = workspacesConfig ?? {};
                 // if the `packages` key is not being used
                 if (!workspaces.packages) {
                     workspaces.packages = addToConfig;
@@ -110,7 +121,12 @@ export const command = async (conf) => {
             // finally, we add the new workspaces to the config file
             save('workspaces', workspaces);
         }
+        // run install to set up node_modules and vlt-lock.json
+        await install({ ...conf.options, allowScripts });
         return results;
     }
-    return init({ cwd: process.cwd() });
+    const result = await init({ cwd: process.cwd() });
+    // run install to set up node_modules and vlt-lock.json
+    await install({ ...conf.options, allowScripts });
+    return result;
 };

package/dist/commands/install.js

@@ -2,6 +2,7 @@ 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";
+import { trackInstall } from "../telemetry.js";
 export const usage = () => commandUsage({
     command: 'install',
     usage: '[packages ...]',
@@ -119,6 +120,7 @@ export const command = async (conf) => {
         String(conf.get('allow-scripts'))
         : ':not(*)';
     /* c8 ignore stop */
+    const installStart = Date.now();
     const { buildQueue, graph, diff } = await install({
         ...conf.options,
         frozenLockfile,
@@ -126,5 +128,13 @@ export const command = async (conf) => {
         allowScripts,
         lockfileOnly,
     }, add);
+    /* c8 ignore next 9 - telemetry is best-effort */
+    try {
+        trackInstall({
+            dependency_count: graph.nodes.size,
+            duration_ms: Date.now() - installStart,
+        }, conf.values.telemetry);
+    }
+    catch { }
     return { buildQueue, graph, diff };
 };

package/dist/commands/profile.d.ts

@@ -0,0 +1,13 @@
+import type { JSONField } from '@vltpkg/types';
+import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const usage: CommandUsage;
+export type ProfileData = Record<string, JSONField>;
+export type ProfileResult = ProfileData | {
+    property: string;
+    value: JSONField;
+};
+export declare const views: {
+    readonly human: (result: ProfileResult) => string;
+    readonly json: (r: ProfileResult) => ProfileResult;
+};
+export declare const command: CommandFn<ProfileResult>;

package/dist/commands/profile.js

@@ -0,0 +1,104 @@
+import { error } from '@vltpkg/error-cause';
+import { RegistryClient } from '@vltpkg/registry-client';
+import { commandUsage } from "../config/usage.js";
+export const usage = () => commandUsage({
+    command: 'profile',
+    usage: '<command> [<args>]',
+    description: `Get or set profile properties for the authenticated user
+                  on the configured registry.`,
+    subcommands: {
+        get: {
+            usage: '[<property>]',
+            description: 'Display profile information. Optionally pass a property name to get a single value.',
+        },
+        set: {
+            usage: '<property> <value>',
+            description: 'Set a profile property to the given value.',
+        },
+    },
+    options: {
+        registry: {
+            value: '<url>',
+            description: 'Registry URL to query for profile info.',
+        },
+        identity: {
+            value: '<name>',
+            description: 'Identity namespace used to look up auth tokens.',
+        },
+        otp: {
+            description: 'Provide an OTP to use when updating profile properties.',
+            value: '<otp>',
+        },
+    },
+});
+const stringify = (v) => typeof v === 'string' ? v
+    : typeof v === 'number' || typeof v === 'boolean' ? `${v}`
+        : v === null ? 'null'
+            : JSON.stringify(v);
+export const views = {
+    human: result => {
+        if ('property' in result) {
+            return stringify(result.value);
+        }
+        return Object.entries(result)
+            .map(([k, v]) => `${k}: ${stringify(v)}`)
+            .join('\n');
+    },
+    json: r => r,
+};
+export const command = async (conf) => {
+    const [sub, ...args] = conf.positionals;
+    switch (sub) {
+        case 'get':
+            return getProfile(conf, args);
+        case 'set':
+            return setProfile(conf, args);
+        default: {
+            throw error('Invalid profile subcommand', {
+                found: sub,
+                validOptions: ['get', 'set'],
+                code: 'EUSAGE',
+            });
+        }
+    }
+};
+const getProfile = async (conf, args) => {
+    const rc = new RegistryClient(conf.options);
+    const registryUrl = new URL(conf.options.registry);
+    const url = new URL('-/npm/v1/user', registryUrl);
+    const response = await rc.request(url, { useCache: false });
+    const data = response.json();
+    const [property] = args;
+    if (property) {
+        if (!(property in data)) {
+            throw error('Property not found in profile', {
+                found: property,
+                validOptions: Object.keys(data),
+                code: 'EUSAGE',
+            });
+        }
+        return { property, value: data[property] };
+    }
+    return data;
+};
+const setProfile = async (conf, args) => {
+    const [property, ...rest] = args;
+    const value = rest.join(' ');
+    if (!property || !value) {
+        throw error('set requires a property name and value', {
+            code: 'EUSAGE',
+        });
+    }
+    const rc = new RegistryClient(conf.options);
+    const registryUrl = new URL(conf.options.registry);
+    const url = new URL('-/npm/v1/user', registryUrl);
+    const response = await rc.request(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ [property]: value }),
+        otp: conf.options.otp,
+        useCache: false,
+    });
+    const data = response.json();
+    return { property, value: data[property] };
+};

package/dist/commands/token.d.ts

@@ -1,3 +1,26 @@
 import type { CommandFn, CommandUsage } from '../index.ts';
+export type TokenInfo = {
+    /** The server-side key/id for the token */
+    key: string;
+    /** A truncated prefix of the token value */
+    token: string;
+    /** ISO date when the token was created */
+    created: string;
+    /** Whether this token is read-only */
+    readonly: boolean;
+    /** CIDR whitelist, if any */
+    cidr_whitelist?: string[];
+};
+export type RegistryTokens = {
+    registry: string;
+    alias?: string;
+    tokens: TokenInfo[];
+    error?: string;
+};
+export type TokenListResult = RegistryTokens[];
 export declare const usage: CommandUsage;
-export declare const command: CommandFn<void>;
+export declare const views: {
+    readonly human: (r: TokenListResult | void) => string | undefined;
+    readonly json: (r: TokenListResult | void) => TokenListResult | undefined;
+};
+export declare const command: CommandFn<TokenListResult | void>;

package/dist/commands/token.js

@@ -1,25 +1,132 @@
 import { error } from '@vltpkg/error-cause';
-import { deleteToken, setToken } from '@vltpkg/registry-client';
+import { deleteToken, normalizeRegistryKey, RegistryClient, setToken, } from '@vltpkg/registry-client';
 import { commandUsage } from "../config/usage.js";
 import { readPassword } from "../read-password.js";
 export const usage = () => commandUsage({
     command: 'token',
-    usage: ['add', 'rm'],
-    description: `Explicitly add or remove tokens in the vlt keychain`,
+    usage: ['list', 'add', 'rm'],
+    description: `Manage registry authentication tokens in the vlt keychain.`,
+    subcommands: {
+        list: {
+            usage: '',
+            description: `List all tokens for configured registries.
+                      Queries each registry's token API and displays
+                      token metadata including key, creation date,
+                      and permissions.`,
+        },
+        add: {
+            usage: '',
+            description: `Add a token for the specified registry.
+                      You will be prompted to paste the bearer token.`,
+        },
+        rm: {
+            usage: '',
+            description: `Remove the stored token for the specified registry.`,
+        },
+    },
     options: {
         registry: {
             value: '<url>',
             description: 'Registry URL to manage tokens for.',
         },
+        registries: {
+            value: '<alias=url>',
+            description: 'Named registry aliases (used by the list subcommand).',
+        },
         identity: {
             value: '<name>',
             description: 'Identity namespace used to store auth tokens.',
         },
     },
 });
+const formatDate = (iso) => {
+    const d = new Date(iso);
+    return d.toLocaleDateString('en-US', {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+    });
+};
+const formatTokenEntry = (t) => {
+    const parts = [
+        `key: ${t.key}`,
+        `token: ${t.token}…`,
+        `created: ${formatDate(t.created)}`,
+        `readonly: ${t.readonly ? 'yes' : 'no'}`,
+    ];
+    if (t.cidr_whitelist && t.cidr_whitelist.length > 0) {
+        parts.push(`cidr: ${t.cidr_whitelist.join(', ')}`);
+    }
+    return parts.join(' │ ');
+};
+const formatRegistryTokens = (r) => {
+    const header = r.alias ? `${r.alias} (${r.registry})` : r.registry;
+    if (r.error)
+        return `${header}\n  error: ${r.error}`;
+    if (r.tokens.length === 0)
+        return `${header}\n  (no tokens found)`;
+    return [
+        header,
+        ...r.tokens.map(t => `  ${formatTokenEntry(t)}`),
+    ].join('\n');
+};
+export const views = {
+    human: (r) => {
+        if (!r)
+            return;
+        return r.map(formatRegistryTokens).join('\n\n');
+    },
+    json: (r) => {
+        if (!r)
+            return;
+        return r;
+    },
+};
+const listTokens = async (rc, registry, alias) => {
+    const tokensUrl = new URL('-/npm/v1/tokens', registry);
+    try {
+        const objects = await rc.scroll(tokensUrl, {
+            useCache: false,
+        });
+        return {
+            registry,
+            alias,
+            tokens: objects.map(o => ({
+                key: o.key,
+                token: o.token,
+                created: o.created,
+                readonly: o.readonly,
+                cidr_whitelist: o.cidr_whitelist,
+            })),
+        };
+    }
+    catch (err) {
+        return {
+            registry,
+            alias,
+            tokens: [],
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+};
 export const command = async (conf) => {
-    const reg = new URL(conf.options.registry).origin;
+    const reg = normalizeRegistryKey(conf.options.registry);
     switch (conf.positionals[0]) {
+        case 'list': {
+            const rc = new RegistryClient(conf.options);
+            const results = [];
+            // Always query the default registry first
+            results.push(await listTokens(rc, conf.options.registry, 'default'));
+            // Then query all configured registry aliases
+            const registries = conf.options.registries;
+            for (const [alias, registry] of Object.entries(registries)) {
+                // Skip if it's the same as the default registry
+                if (registry !== conf.options.registry) {
+                    results.push(await listTokens(rc, registry, alias));
+                }
+            }
+            return results;
+        }
         case 'add': {
             await setToken(reg, `Bearer ${await readPassword('Paste bearer token: ')}`, conf.options.identity);
             break;
@@ -31,7 +138,7 @@ export const command = async (conf) => {
         default: {
             throw error('Invalid token subcommand', {
                 found: conf.positionals[0],
-                validOptions: ['add', 'rm'],
+                validOptions: ['list', 'add', 'rm'],
                 code: 'EUSAGE',
             });
         }

package/dist/commands/unpublish.d.ts

@@ -0,0 +1,15 @@
+import type { CommandFn, CommandUsage } from '../index.ts';
+export declare const usage: CommandUsage;
+export type CommandResult = {
+    /** The package name */
+    name: string;
+    /** The version that was unpublished, or undefined for entire package */
+    version?: string;
+    /** The registry URL */
+    registry: string;
+};
+export declare const views: {
+    readonly human: (result: CommandResult) => string;
+    readonly json: (r: CommandResult) => CommandResult;
+};
+export declare const command: CommandFn<CommandResult>;

package/dist/commands/unpublish.js

@@ -0,0 +1,200 @@
+import { error } from '@vltpkg/error-cause';
+import { RegistryClient } from '@vltpkg/registry-client';
+import { Spec } from '@vltpkg/spec';
+import { asError } from '@vltpkg/types';
+import { commandUsage } from "../config/usage.js";
+export const usage = () => commandUsage({
+    command: 'unpublish',
+    usage: ['<package>@<version>', '<package> --force'],
+    description: `Remove a package version from the registry.
+
+    To unpublish a single version, specify the package name and version.
+    To unpublish an entire package, specify the package name and use --force.
+
+    ⚠️  Unpublishing is a destructive action that cannot be undone.
+    Consider using \`vlt deprecate\` instead if you want to discourage
+    usage of a package without removing it.`,
+    examples: {
+        'my-package@1.0.0': {
+            description: 'Unpublish a specific version',
+        },
+        '@scope/my-package@1.0.0': {
+            description: 'Unpublish a specific version of a scoped package',
+        },
+        'my-package --force': {
+            description: 'Unpublish an entire package (requires --force)',
+        },
+    },
+    options: {
+        force: {
+            description: 'Required to unpublish an entire package (all versions).',
+        },
+        otp: {
+            description: 'Provide a one-time password for authentication.',
+            value: '<otp>',
+        },
+    },
+});
+export const views = {
+    human: (result) => {
+        if (result.version) {
+            return `⚠️  ${result.name}@${result.version} has been unpublished from ${result.registry}.`;
+        }
+        return `⚠️  ${result.name} (all versions) has been unpublished from ${result.registry}.`;
+    },
+    json: (r) => r,
+};
+export const command = async (conf) => {
+    const specArg = conf.positionals[0];
+    if (!specArg) {
+        throw error('unpublish requires a package spec argument (e.g. pkg@version)', { code: 'EUSAGE' });
+    }
+    const { registry, otp, force } = conf.options;
+    const registryUrl = new URL(registry);
+    const spec = Spec.parseArgs(specArg, conf.options);
+    const name = spec.name;
+    /* c8 ignore start - Spec.parseArgs always produces a name for valid input */
+    if (!name) {
+        throw error('Package name is required', {
+            found: specArg,
+        });
+    }
+    /* c8 ignore stop */
+    const version = spec.bareSpec;
+    // If no version specified, require --force to unpublish the entire package
+    if (!version) {
+        if (!force) {
+            throw error('Refusing to unpublish entire package without --force.\n' +
+                'To unpublish a specific version, use: vlt unpublish <package>@<version>\n' +
+                'To unpublish all versions, use: vlt unpublish <package> --force');
+        }
+    }
+    const rc = new RegistryClient(conf.options);
+    const encodedName = name.startsWith('@') ? name.replace('/', '%2F') : name;
+    if (version) {
+        // Unpublish a specific version:
+        // 1. Fetch the packument
+        // 2. Remove the version from the packument
+        // 3. PUT the updated packument back
+        const packumentUrl = new URL(encodedName, registryUrl);
+        let packumentResponse;
+        try {
+            packumentResponse = await rc.request(packumentUrl, {
+                useCache: false,
+            });
+        }
+        catch (err) {
+            throw error('Failed to fetch package metadata', {
+                cause: asError(err),
+            });
+        }
+        if (packumentResponse.statusCode !== 200) {
+            throw error('Package not found on the registry', {
+                url: packumentUrl,
+                response: packumentResponse,
+            });
+        }
+        const packument = packumentResponse.json();
+        const versions = packument.versions;
+        const distTags = packument['dist-tags'];
+        if (!versions?.[version]) {
+            throw error(`Version ${version} not found in package ${name}`, {
+                found: version,
+                wanted: Object.keys(versions ?? {}),
+            });
+        }
+        // Remove the version
+        delete versions[version];
+        // Remove any dist-tags pointing to this version
+        if (distTags) {
+            for (const [tag, tagVersion] of Object.entries(distTags)) {
+                if (tagVersion === version) {
+                    delete distTags[tag];
+                }
+            }
+        }
+        // Remove the version from the time field if present
+        const time = packument.time;
+        if (time?.[version]) {
+            delete time[version];
+        }
+        // PUT the updated packument
+        const putUrl = new URL(`${encodedName}/-rev/${packument._rev}`, registryUrl);
+        let response;
+        try {
+            response = await rc.request(putUrl, {
+                method: 'PUT',
+                headers: {
+                    'content-type': 'application/json',
+                    'npm-auth-type': 'web',
+                    'npm-command': 'unpublish',
+                },
+                body: JSON.stringify(packument),
+                otp,
+            });
+        }
+        catch (err) {
+            throw error('Failed to unpublish package version', {
+                cause: asError(err),
+            });
+        }
+        if (response.statusCode !== 200 && response.statusCode !== 201) {
+            throw error('Failed to unpublish package version', {
+                url: putUrl,
+                response,
+            });
+        }
+    }
+    else {
+        // Unpublish entire package — DELETE the packument
+        // First fetch the packument to get the _rev
+        const packumentUrl = new URL(encodedName, registryUrl);
+        let packumentResponse;
+        try {
+            packumentResponse = await rc.request(packumentUrl, {
+                useCache: false,
+            });
+        }
+        catch (err) {
+            throw error('Failed to fetch package metadata', {
+                cause: asError(err),
+            });
+        }
+        if (packumentResponse.statusCode !== 200) {
+            throw error('Package not found on the registry', {
+                url: packumentUrl,
+                response: packumentResponse,
+            });
+        }
+        const packument = packumentResponse.json();
+        const deleteUrl = new URL(`${encodedName}/-rev/${packument._rev}`, registryUrl);
+        let response;
+        try {
+            response = await rc.request(deleteUrl, {
+                method: 'DELETE',
+                headers: {
+                    'content-type': 'application/json',
+                    'npm-auth-type': 'web',
+                    'npm-command': 'unpublish',
+                },
+                otp,
+            });
+        }
+        catch (err) {
+            throw error('Failed to unpublish package', {
+                cause: asError(err),
+            });
+        }
+        if (response.statusCode !== 200 && response.statusCode !== 201) {
+            throw error('Failed to unpublish package', {
+                url: deleteUrl,
+                response,
+            });
+        }
+    }
+    return {
+        name,
+        ...(version ? { version } : {}),
+        registry: registryUrl.origin,
+    };
+};