@ultikits/cli 1.2.0 → 2.0.1

package/dist/src/commands/publish.d.ts

@@ -1,5 +1,9 @@
 import { Command } from 'commander';
+import { ApiError } from '../lib/api-client.js';
+import { type Io } from '../lib/logger.js';
 import type { ModuleMetadata, ProjectConfig, PluginYml } from '../types.js';
+/** Upload limit from the contract (versionsCreate.sizeBytes maximum). */
+export declare const MAX_JAR_BYTES = 52428800;
 interface PublishFlags {
     id?: string;
     name?: string;
@@ -7,6 +11,30 @@ interface PublishFlags {
     changelog?: string;
     shortDescription?: string;
 }
+export interface PublishOptions extends PublishFlags {
+    yes?: boolean;
+    apiUrl?: string;
+}
+export interface CommandDeps {
+    env?: NodeJS.ProcessEnv;
+    configDir?: string;
+    cwd?: string;
+    io?: Io;
+    prompt?: (questions: any[]) => Promise<Record<string, any>>;
+}
 export declare function resolveMetadata(flags: PublishFlags, projectConfig: ProjectConfig | null, pluginYml: PluginYml | null): ModuleMetadata;
 export declare function registerPublishCommand(program: Command): void;
+export declare function runPublish(jarPath: string | undefined, options: PublishOptions, deps?: CommandDeps): Promise<number>;
+export interface PublishErrorContext {
+    identifier: string;
+    version: string;
+    apiUrl: string;
+    phase?: 'publish' | 'createModule';
+}
+/**
+ * One message per error code of the developer-client contract (keys must be codes
+ * that appear in tests/contract/.../schemas; DEVELOPER-CLIENT.md "错误码与客户端动作").
+ */
+export declare const PUBLISH_ERROR_MESSAGES: Record<string, (err: ApiError, ctx: PublishErrorContext) => string>;
+export declare function publishErrorMessage(err: unknown, ctx: PublishErrorContext): string;
 export {};

package/dist/src/commands/publish.js

@@ -1,11 +1,14 @@
 import fs from 'node:fs';
-import path from 'node:path';
+import { createHash } from 'node:crypto';
 import inquirer from 'inquirer';
-import { readCredentials } from '../lib/config.js';
+import { resolveAuth, developerCentreUrl } from '../lib/config.js';
 import { readProjectConfig } from '../lib/project-config.js';
 import { readPluginYml, findJarInTarget } from '../lib/jar-reader.js';
-import { ApiClient } from '../lib/api-client.js';
-import * as log from '../lib/logger.js';
+import { ApiClient, ApiError } from '../lib/api-client.js';
+import { redact } from '../lib/mask.js';
+import { consoleIo } from '../lib/logger.js';
+/** Upload limit from the contract (versionsCreate.sizeBytes maximum). */
+export const MAX_JAR_BYTES = 52428800;
 export function resolveMetadata(flags, projectConfig, pluginYml) {
     const identifyString = flags.id ?? projectConfig?.identifyString;
     const name = flags.name ?? projectConfig?.name ?? pluginYml?.name;
@@ -16,16 +19,14 @@ export function resolveMetadata(flags, projectConfig, pluginYml) {
     const missing = [];
     if (!identifyString)
         missing.push('identifyString (use --id or ultikits.json)');
-    if (!name)
-        missing.push('name (use --name, ultikits.json, or plugin.yml)');
     if (!version)
-        missing.push('version (use --version or plugin.yml in JAR)');
+        missing.push('version (use --module-version or plugin.yml in JAR)');
     if (missing.length > 0) {
         throw new Error('Missing required fields:\n  - ' + missing.join('\n  - '));
     }
     return {
         identifyString: identifyString,
-        name: name,
+        name: name || undefined,
         version: version,
         shortDescription,
         changelog,
@@ -35,137 +36,200 @@ export function resolveMetadata(flags, projectConfig, pluginYml) {
 export function registerPublishCommand(program) {
     program
         .command('publish [jar-path]')
-        .description('Publish a plugin module to UltiCloud')
-        .option('--id <identifyString>', 'Module identify string')
-        .option('--name <name>', 'Module display name')
-        .option('--module-version <version>', 'Module version')
+        .description('Publish a plugin module version to UltiCloud')
+        .option('--id <identifyString>', 'Module identifier')
+        .option('--name <name>', 'Module display name (used only when the module has to be created)')
+        .option('--module-version <version>', 'Module version (default: plugin.yml version)')
         .option('--changelog <text>', 'Version changelog')
-        .option('--short-description <text>', 'Short description')
+        .option('--short-description <text>', 'Short description (used only when the module has to be created)')
+        .option('--api-url <url>', 'UltiCloud API URL (default: ULTIKITS_API_URL, stored login, or https://api.ultikits.com)')
         .option('-y, --yes', 'Skip confirmation prompts')
         .action(async (jarPath, options) => {
-        // 1. Resolve auth
-        const credentials = readCredentials();
-        const client = ApiClient.fromEnvOrCredentials(credentials);
-        if (!client) {
-            log.error('Not logged in. Run `ultikits login` or set ULTIKITS_TOKEN.');
-            process.exit(1);
-        }
-        // 2. Resolve JAR path
-        const resolvedJarPath = jarPath ?? findJarInTarget();
-        if (!resolvedJarPath) {
-            log.error('No JAR file specified and none found in ./target/');
-            log.info('Usage: ultikits publish <path-to-jar>');
-            process.exit(1);
-        }
-        if (!fs.existsSync(resolvedJarPath)) {
-            log.error(`File not found: ${resolvedJarPath}`);
-            process.exit(1);
-        }
-        // 3. Read plugin.yml from JAR
-        const pluginYml = await readPluginYml(resolvedJarPath);
-        if (pluginYml) {
-            log.success(`Read plugin.yml from JAR: name=${pluginYml.name}, version=${pluginYml.version}`);
-        }
-        // 4. Read project config
-        const projectConfig = readProjectConfig();
-        if (projectConfig) {
-            log.success(`Using config from ultikits.json: id=${projectConfig.identifyString}`);
-        }
-        // 5. Resolve metadata
-        let metadata;
-        try {
-            metadata = resolveMetadata(options, projectConfig, pluginYml);
-        }
-        catch (err) {
-            log.error(err.message);
-            process.exit(1);
-        }
-        // 6. Show summary
-        const fileSize = fs.statSync(resolvedJarPath).size;
-        console.log();
-        console.log(`  Module:  ${metadata.name}`);
-        console.log(`  ID:      ${metadata.identifyString}`);
-        console.log(`  Version: ${metadata.version}`);
-        console.log(`  Size:    ${(fileSize / 1024).toFixed(0)} KB`);
-        console.log();
-        // 7. Ask for changelog if not provided
-        if (!metadata.changelog && !options.yes) {
-            const { changelog } = await inquirer.prompt([
-                {
-                    type: 'input',
-                    name: 'changelog',
-                    message: 'Changelog (optional):',
-                },
-            ]);
+        process.exitCode = await runPublish(jarPath, options);
+    });
+}
+export async function runPublish(jarPath, options, deps = {}) {
+    const io = deps.io ?? consoleIo;
+    const env = deps.env ?? process.env;
+    const cwd = deps.cwd ?? process.cwd();
+    const prompt = deps.prompt ?? ((q) => inquirer.prompt(q));
+    // 1. Credential and API origin; nothing is sent before both are valid.
+    const auth = resolveAuth({ apiUrl: options.apiUrl, env, configDir: deps.configDir });
+    if (!auth.ok) {
+        io.err(auth.message);
+        return 1;
+    }
+    // 2. JAR: read once; the same bytes are hashed, measured and uploaded.
+    const resolvedJarPath = jarPath ?? findJarInTarget(cwd);
+    if (!resolvedJarPath) {
+        io.err('No JAR file specified and none found in ./target/ (usage: ultikits publish <path-to-jar>)');
+        return 1;
+    }
+    let bytes;
+    try {
+        bytes = fs.readFileSync(resolvedJarPath);
+    }
+    catch {
+        io.err(`File not found: ${resolvedJarPath}`);
+        return 1;
+    }
+    if (bytes.length > MAX_JAR_BYTES) {
+        io.err(`JAR 大小 ${bytes.length} 字节超过上限 ${MAX_JAR_BYTES} 字节（50 MiB），未发送任何请求。`);
+        return 1;
+    }
+    const pluginYml = await readPluginYml(resolvedJarPath);
+    const projectConfig = readProjectConfig(cwd);
+    let metadata;
+    try {
+        metadata = resolveMetadata(options, projectConfig, pluginYml);
+    }
+    catch (err) {
+        io.err(err.message);
+        return 1;
+    }
+    const sha256 = createHash('sha256').update(bytes).digest('hex');
+    io.out(`  Module:  ${metadata.identifyString}`);
+    io.out(`  Version: ${metadata.version}`);
+    io.out(`  Size:    ${(bytes.length / 1024).toFixed(0)} KB`);
+    io.out(`  API:     ${auth.apiUrl}`);
+    if (!options.yes) {
+        if (metadata.changelog === undefined) {
+            const { changelog } = await prompt([{ type: 'input', name: 'changelog', message: 'Changelog (optional):' }]);
             if (changelog)
                 metadata.changelog = changelog;
         }
-        // 8. Confirm
-        if (!options.yes) {
-            const { confirm } = await inquirer.prompt([
-                {
-                    type: 'confirm',
-                    name: 'confirm',
-                    message: `Publish ${metadata.identifyString}@${metadata.version}?`,
-                    default: true,
-                },
-            ]);
-            if (!confirm)
-                return;
+        const { confirm } = await prompt([
+            { type: 'confirm', name: 'confirm', message: `Publish ${metadata.identifyString}@${metadata.version}?`, default: true },
+        ]);
+        if (!confirm)
+            return 1;
+    }
+    const client = new ApiClient({ apiUrl: auth.apiUrl, credential: auth.credential });
+    const ref = metadata.identifyString;
+    const label = `${ref}@${metadata.version}`;
+    const ctx = { identifier: ref, version: metadata.version, apiUrl: auth.apiUrl };
+    const versionBody = {
+        version: metadata.version,
+        changelog: metadata.changelog ?? null,
+        sha256,
+        sizeBytes: bytes.length,
+    };
+    try {
+        let ticket;
+        try {
+            ticket = await declareVersion(client, ref, versionBody, io, label);
         }
-        // 9. Check if module exists
-        const spin = log.spinner('Checking module...');
-        spin.start();
-        const pluginRes = await client.get(`/plugin/get?identifyString=${metadata.identifyString}`);
-        let moduleId;
-        if (pluginRes.code !== '200' || !pluginRes.data) {
-            // Module doesn't exist — create it
-            spin.text = 'Creating module...';
-            const createRes = await client.post('/developer/modules', {
-                name: metadata.name,
-                identifyString: metadata.identifyString,
-                shortDescription: metadata.shortDescription ?? '',
-                categoryId: metadata.categoryId,
-            });
-            if (createRes.code !== '200') {
-                spin.fail('Failed to create module: ' + createRes.msg);
-                process.exit(1);
+        catch (err) {
+            if (!(err instanceof ApiError && err.code === 'not_found'))
+                throw err;
+            // The module does not exist yet: create it (needs a manage credential), then retry once.
+            const name = metadata.name;
+            if (!name) {
+                io.err(`模块 ${ref} 不存在，且取不到模块名称：请用 --name 指定名称（或写进 ultikits.json）后重试。`);
+                return 1;
             }
-            moduleId = createRes.data.id;
-            spin.succeed('Module created');
-        }
-        else {
-            moduleId = pluginRes.data.id;
-            spin.succeed('Module found');
-        }
-        // 10. Create version
-        const versionSpin = log.spinner(`Creating version ${metadata.version}...`);
-        versionSpin.start();
-        const versionRes = await client.post(`/developer/modules/${moduleId}/versions`, {
-            version: metadata.version,
-            changelog: metadata.changelog,
-        });
-        if (versionRes.code !== '200') {
-            versionSpin.fail('Failed to create version: ' + versionRes.msg);
-            process.exit(1);
-        }
-        const { uploadToken } = versionRes.data;
-        versionSpin.succeed('Upload token acquired');
-        // 11. Upload JAR
-        const uploadSpin = log.spinner('Uploading JAR...');
-        uploadSpin.start();
-        const fileBuffer = fs.readFileSync(resolvedJarPath);
-        const blob = new Blob([fileBuffer]);
-        const formData = new FormData();
-        formData.append('file', blob, path.basename(resolvedJarPath));
-        const uploadRes = await client.postMultipart(`/developer/modules/${moduleId}/upload`, formData, { 'X-Upload-Token': uploadToken });
-        if (uploadRes.code !== '200') {
-            uploadSpin.fail('Upload failed: ' + uploadRes.msg);
-            process.exit(1);
+            io.out(`模块 ${ref} 不存在，正在创建…`);
+            try {
+                await client.createModule({
+                    identifier: ref,
+                    name,
+                    shortDescription: (metadata.shortDescription ?? '').slice(0, 200),
+                    categoryId: metadata.categoryId ?? null,
+                    description: null,
+                    compatibleApiVersions: null,
+                    tags: [],
+                });
+            }
+            catch (createErr) {
+                throw new PhaseError('createModule', createErr);
+            }
+            io.out(`模块 ${ref} 已创建。`);
+            ticket = await declareVersion(client, ref, versionBody, io, label);
         }
-        uploadSpin.succeed(`Published ${metadata.identifyString}@${metadata.version}`);
-        console.log();
-        log.info(`https://panel.ultikits.com/modules/${metadata.identifyString}`);
-    });
+        io.out(`正在上传 ${bytes.length} 字节…`);
+        await client.uploadJar(ticket, bytes);
+    }
+    catch (err) {
+        const phase = err instanceof PhaseError ? err.phase : 'publish';
+        const cause = err instanceof PhaseError ? err.cause : err;
+        io.err(redact(publishErrorMessage(cause, { ...ctx, phase }), auth.credential));
+        return 1;
+    }
+    io.out(`已发布 ${label}`);
+    const centre = developerCentreUrl(auth.apiUrl);
+    if (centre)
+        io.out(centre);
+    return 0;
+}
+/** Creates the version, or re-signs the ticket of a version still waiting for its upload. */
+async function declareVersion(client, ref, body, io, label) {
+    try {
+        const created = await client.createVersion(ref, body);
+        io.out(`已创建版本 ${label}。`);
+        return created.upload;
+    }
+    catch (err) {
+        if (!(err instanceof ApiError && err.code === 'version_exists'))
+            throw err;
+        io.out(`版本 ${label} 已存在且等待上传，正在重签上传票据续传…`);
+        return client.requestUploadToken(ref, body.version);
+    }
+}
+class PhaseError extends Error {
+    phase;
+    cause;
+    constructor(phase, cause) {
+        super('phase error');
+        this.phase = phase;
+        this.cause = cause;
+    }
+}
+function centreSuffix(apiUrl) {
+    const centre = developerCentreUrl(apiUrl);
+    return centre ? `：${centre}` : '。';
+}
+function fieldList(err) {
+    const fields = err.details?.fields;
+    if (!fields || typeof fields !== 'object')
+        return '';
+    return Object.entries(fields)
+        .map(([field, reason]) => `${field}: ${String(reason)}`)
+        .join('；');
+}
+/**
+ * One message per error code of the developer-client contract (keys must be codes
+ * that appear in tests/contract/.../schemas; DEVELOPER-CLIENT.md "错误码与客户端动作").
+ */
+export const PUBLISH_ERROR_MESSAGES = {
+    invalid_credential: () => '凭据无效或已过期，请重新 ultikits login（或更换 ULTIKITS_TOKEN）。',
+    role_required: (_e, c) => `该账号还不是开发者，请先去开发者中心申请${centreSuffix(c.apiUrl)}`,
+    not_found: (_e, c) => `模块 ${c.identifier} 或版本 ${c.version} 不存在，请检查标识符${centreSuffix(c.apiUrl)}`,
+    version_exists: (_e, c) => `${c.identifier}@${c.version} 已存在，无法续传。`,
+    version_not_greater: (_e, c) => `版本号 ${c.version} 不大于 ${c.identifier} 已有的最新版本，请提高版本号。`,
+    version_not_pending: (_e, c) => `${c.identifier}@${c.version} 已发布，请升版本号。`,
+    version_format_invalid: (_e, c) => `版本号 ${c.version} 格式不对，应为 X.Y.Z（可带预发布后缀）。`,
+    storage_quota_exceeded: () => '存储配额已用完：请撤回旧版本或联系支持。',
+    payload_too_large: () => '请求体过大，服务器拒绝。',
+    validation_failed: (e, c) => `${c.phase === 'createModule' ? '建模块的资料' : '请求参数'}不合格${fieldList(e) ? `：${fieldList(e)}` : '。'}`,
+    upload_token_expired: () => '上传票据已过期：请重新运行同一条 ultikits publish（版本仍在等待上传时会自动重签票据续传）。',
+    upload_too_large: () => '文件超过声明的大小或 50 MiB 上限：请检查构建产物。',
+    upload_invalid_file_type: () => '服务器只接受 application/java-archive（JAR）文件。',
+    upload_checksum_mismatch: () => '服务器收到的文件 SHA-256 与声明不一致（文件可能在上传过程中被改动）：请确认构建产物后重新发布。',
+    upload_jar_invalid: () => '上传的文件不是有效的 ZIP/JAR：检查构建产物路径。',
+    upload_api_level_missing: () => 'JAR 里的 plugin.yml 需要整数 api-version：补上后重新构建再发布。',
+    rate_limited: (e) => `请求过于频繁，请 ${e.retryAfterSeconds ?? '稍'} 秒后再试（不会自动重试）。`,
+    key_scope_insufficient: (_e, c) => `模块 ${c.identifier} 不存在；建模块需要 manage 凭据（ultikits login，或把开发者密钥轮换为管理作用域），也可以先在开发者中心建${centreSuffix(c.apiUrl)}`,
+    module_identifier_taken: (_e, c) => `建模块失败：标识符 ${c.identifier} 已被占用。若这是你 30 天内删除的模块，可用 ultikits modules restore ${c.identifier} 恢复。`,
+    module_name_taken: (_e, c) => `建模块失败：模块名称已被占用。若这是你 30 天内删除的模块，可用 ultikits modules restore ${c.identifier} 恢复；否则用 --name 换一个名称。`,
+};
+export function publishErrorMessage(err, ctx) {
+    if (err instanceof ApiError) {
+        const describe = PUBLISH_ERROR_MESSAGES[err.code];
+        const id = err.requestId ? ` (requestId ${err.requestId})` : '';
+        if (describe)
+            return `${describe(err, ctx)} [${err.code}]${id}`;
+        return `发布 ${ctx.identifier}@${ctx.version} 失败：${err.message} [${err.code}]${id}`;
+    }
+    return `发布 ${ctx.identifier}@${ctx.version} 失败：${err?.message ?? String(err)}`;
 }
 //# sourceMappingURL=publish.js.map

package/dist/src/commands/versions.d.ts

@@ -1,2 +1,12 @@
 import { Command } from 'commander';
+import { type DestructiveOptions, type ManageDeps } from './modules.js';
 export declare function registerVersionsCommand(program: Command): void;
+/**
+ * The API that authenticated commands would use (same rule as resolveAuth): with
+ * ULTIKITS_TOKEN set, the stored login's API is ignored. Never reads the credential value.
+ */
+export declare function publicApiUrl(flag: string | undefined, env: NodeJS.ProcessEnv, configDir?: string): string;
+export declare function runVersionsList(identifier: string, options: {
+    apiUrl?: string;
+}, deps?: ManageDeps): Promise<number>;
+export declare function runVersionsWithdraw(identifier: string, version: string, options: DestructiveOptions, deps?: ManageDeps): Promise<number>;

package/dist/src/commands/versions.js

@@ -1,76 +1,110 @@
-import inquirer from 'inquirer';
-import { readCredentials } from '../lib/config.js';
+import { resolveApiUrl, readCredentials, resolveAuth } from '../lib/config.js';
 import { ApiClient } from '../lib/api-client.js';
-import * as log from '../lib/logger.js';
+import { redact } from '../lib/mask.js';
+import { consoleIo } from '../lib/logger.js';
+import { fetchAllPages, MAX_PAGE_SIZE } from '../lib/paging.js';
+import { isInteractiveTerminal, requireConfirmation } from '../lib/confirm.js';
+import { describeCommandError } from '../lib/command-errors.js';
+import { EXIT_USAGE } from './modules.js';
+const API_URL_HELP = 'UltiCloud API URL (default: ULTIKITS_API_URL, stored login, or https://api.ultikits.com)';
 export function registerVersionsCommand(program) {
-    const versions = program
-        .command('versions')
-        .description('Manage module versions');
+    const versions = program.command('versions').description('List and withdraw module versions');
     versions
-        .command('list <identifyString>')
-        .description('List versions of a module')
-        .action(async (identifyString) => {
-        const client = getClient();
-        // Get module ID
-        const infoRes = await client.get(`/plugin/get?identifyString=${identifyString}`);
-        if (infoRes.code !== '200' || !infoRes.data) {
-            log.error('Module not found: ' + identifyString);
-            process.exit(1);
-        }
-        const res = await client.get(`/plugin/${infoRes.data.id}/versions`);
-        if (res.code !== '200') {
-            log.error('Failed to list versions: ' + res.msg);
-            process.exit(1);
-        }
-        const versionsList = res.data;
-        if (versionsList.length === 0) {
-            log.info('No versions published yet.');
-            return;
-        }
-        console.log();
-        for (const v of versionsList) {
-            const latest = v.is_latest ? ' (latest)' : '';
-            const size = v.file_size ? ` ${(v.file_size / 1024).toFixed(0)} KB` : '';
-            console.log(`  ${v.version}${latest}${size} — ${v.created_at}`);
-        }
-        console.log();
-        log.info(`${versionsList.length} version(s)`);
+        .command('list <identifier>')
+        .description('List the published and withdrawn versions of a module (public catalogue, no credential sent)')
+        .option('--api-url <url>', API_URL_HELP)
+        .action(async (identifier, options) => {
+        process.exitCode = await runVersionsList(identifier, options);
     });
-    versions
-        .command('delete <identifyString> <version>')
-        .description('Delete a specific version')
-        .action(async (identifyString, version) => {
-        const client = getClient();
-        const infoRes = await client.get(`/plugin/get?identifyString=${identifyString}`);
-        if (infoRes.code !== '200' || !infoRes.data) {
-            log.error('Module not found: ' + identifyString);
-            process.exit(1);
-        }
-        const { confirm } = await inquirer.prompt([
-            {
-                type: 'confirm',
-                name: 'confirm',
-                message: `Delete version ${version} of "${identifyString}"?`,
-                default: false,
-            },
-        ]);
-        if (!confirm)
-            return;
-        const res = await client.delete(`/developer/modules/${infoRes.data.id}/versions/${version}`);
-        if (res.code !== '200') {
-            log.error('Failed to delete version: ' + res.msg);
-            process.exit(1);
-        }
-        log.success(`Deleted version ${version}`);
+    const withdrawDescription = 'Withdraw a published version. Irreversible: this version and lower ones can never be published again ' +
+        '(needs a manage credential)';
+    const addWithdrawOptions = (cmd) => cmd
+        .option('--confirm <identifier@version>', 'Required with -y or without a terminal: <identifier>@<version>')
+        .option('-y, --yes', 'Do not prompt (still requires --confirm)')
+        .option('--api-url <url>', API_URL_HELP);
+    addWithdrawOptions(versions.command('withdraw <identifier> <version>').description(withdrawDescription)).action(async (identifier, version, options) => {
+        process.exitCode = await runVersionsWithdraw(identifier, version, options);
+    });
+    addWithdrawOptions(versions
+        .command('delete <identifier> <version>')
+        .description('Old name of `versions withdraw` (an irreversible withdrawal, not a delete)')).action(async (identifier, version, options) => {
+        consoleIo.err('注意：versions delete 现在就是 versions withdraw——撤回不可恢复，不是可恢复的删除。');
+        process.exitCode = await runVersionsWithdraw(identifier, version, options);
     });
 }
-function getClient() {
-    const credentials = readCredentials();
-    const client = ApiClient.fromEnvOrCredentials(credentials);
-    if (!client) {
-        log.error('Not logged in. Run `ultikits login` or set ULTIKITS_TOKEN.');
-        process.exit(1);
+/**
+ * The API that authenticated commands would use (same rule as resolveAuth): with
+ * ULTIKITS_TOKEN set, the stored login's API is ignored. Never reads the credential value.
+ */
+export function publicApiUrl(flag, env, configDir) {
+    if (env.ULTIKITS_TOKEN?.trim())
+        return resolveApiUrl(flag, env);
+    const state = readCredentials(configDir);
+    return resolveApiUrl(flag, env, state.status === 'ok' ? state.credential.apiUrl : undefined);
+}
+export async function runVersionsList(identifier, options, deps = {}) {
+    const io = deps.io ?? consoleIo;
+    const env = deps.env ?? process.env;
+    let apiUrl;
+    try {
+        // Public route: only the API origin is needed, never the credential.
+        apiUrl = publicApiUrl(options.apiUrl, env, deps.configDir);
+    }
+    catch (err) {
+        io.err(err.message);
+        return 1;
+    }
+    const client = new ApiClient({ apiUrl });
+    let items;
+    try {
+        items = await fetchAllPages((page) => client.listPublicVersions(identifier, { page, pageSize: MAX_PAGE_SIZE, includeWithdrawn: true }));
+    }
+    catch (err) {
+        io.err(describeCommandError(err, { op: 'versions', identifier, apiUrl }));
+        return 1;
+    }
+    if (items.length === 0) {
+        io.out(`${identifier} 还没有已发布的版本（等待上传的版本不在公开目录里）。`);
+        return 0;
+    }
+    for (const v of items) {
+        const marks = [v.isLatest ? '最新 / latest' : '', v.download.kind === 'withdrawn' ? `已撤回 / withdrawn ${v.download.withdrawnAt}` : '']
+            .filter(Boolean)
+            .join(', ');
+        io.out(`  ${v.version}${marks ? ` [${marks}]` : ''} — ${(v.sizeBytes / 1024).toFixed(0)} KB, ${v.publishedAt}`);
+    }
+    io.out(`共 ${items.length} 个版本 / ${items.length} version(s)`);
+    return 0;
+}
+export async function runVersionsWithdraw(identifier, version, options, deps = {}) {
+    const io = deps.io ?? consoleIo;
+    const target = `${identifier}@${version}`;
+    const confirmed = await requireConfirmation({
+        expected: target,
+        flagValue: options.confirm,
+        yes: options.yes,
+        interactive: deps.interactive ?? isInteractiveTerminal(),
+        warning: `将撤回 ${target}。撤回不可恢复：版本号 ${version} 及更低版本不能再发布；已下载的副本不受影响。`,
+        ask: deps.ask,
+    });
+    if (!confirmed.ok) {
+        io.err(confirmed.reason);
+        return EXIT_USAGE;
+    }
+    const auth = resolveAuth({ apiUrl: options.apiUrl, env: deps.env ?? process.env, configDir: deps.configDir });
+    if (!auth.ok) {
+        io.err(auth.message);
+        return 1;
+    }
+    const client = new ApiClient({ apiUrl: auth.apiUrl, credential: auth.credential });
+    try {
+        await client.withdrawVersion(identifier, version);
+        io.out(`已撤回 ${target}（不可恢复）。`);
+        return 0;
+    }
+    catch (err) {
+        io.err(redact(describeCommandError(err, { op: 'withdraw', identifier, version, apiUrl: auth.apiUrl }), auth.credential));
+        return 1;
     }
-    return client;
 }
 //# sourceMappingURL=versions.js.map

package/dist/src/commands/whoami.d.ts

@@ -1,2 +1,8 @@
 import { Command } from 'commander';
+import type { CommandDeps } from './publish.js';
 export declare function registerWhoamiCommand(program: Command): void;
+/** Message for the identity errors every authenticated command can hit. */
+export declare function describeAuthError(err: unknown, apiUrl: string): string;
+export declare function runWhoami(options: {
+    apiUrl?: string;
+}, deps?: CommandDeps): Promise<number>;