@ultikits/cli 1.2.0 → 2.0.0

package/dist/src/lib/api-client.d.ts

@@ -1,13 +1,58 @@
-import type { Credentials, ApiResponse } from '../types.js';
+import type { CreateModuleBody, CreateVersionBody, CreateVersionResult, DeveloperModule, DeviceAuthorization, DeviceTokenResult, DevModuleVersion, ModuleDeletion, ModuleListItem, Page, PublicModuleVersion, UpdateModuleBody, UploadTicket, WithdrawnVersion, Whoami } from '../types.js';
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string | undefined;
+    readonly details?: Record<string, any> | undefined;
+    constructor(status: number, code: string, message: string, requestId?: string | undefined, details?: Record<string, any> | undefined);
+    /** Seconds to wait from details.retryAfterSeconds or the Retry-After header. */
+    get retryAfterSeconds(): number | undefined;
+}
+export interface ApiClientOptions {
+    apiUrl: string;
+    /** ucd_ or ucc_; omitted for the public device-authorization routes. */
+    credential?: string | null;
+}
 export declare class ApiClient {
-    private baseUrl;
-    private credentials;
-    constructor(credentials: Credentials);
-    static fromEnvOrCredentials(credentials: Credentials | null): ApiClient | null;
-    private getHeaders;
-    get<T = any>(path: string): Promise<ApiResponse<T>>;
-    post<T = any>(path: string, body?: any): Promise<ApiResponse<T>>;
-    postMultipart<T = any>(path: string, formData: FormData, extraHeaders?: Record<string, string>): Promise<ApiResponse<T>>;
-    put<T = any>(path: string, body?: any): Promise<ApiResponse<T>>;
-    delete<T = any>(path: string): Promise<ApiResponse<T>>;
+    readonly apiUrl: string;
+    private readonly credential;
+    constructor(options: ApiClientOptions);
+    request<T>(method: string, path: string, body?: unknown, opts?: {
+        auth?: boolean;
+    }): Promise<T>;
+    deviceAuthorize(suggestedName?: string): Promise<DeviceAuthorization>;
+    deviceToken(deviceCode: string): Promise<DeviceTokenResult>;
+    whoami(): Promise<Whoami>;
+    revokeCurrentCredential(): Promise<{
+        ok: true;
+    }>;
+    createModule(body: CreateModuleBody): Promise<DeveloperModule>;
+    listModules(query: {
+        page: number;
+        pageSize: number;
+        q?: string;
+    }): Promise<Page<ModuleListItem>>;
+    updateModule(moduleRef: string, body: UpdateModuleBody): Promise<ModuleListItem>;
+    /** Recoverable delete: the module can be restored until `restorableUntil`. */
+    deleteModule(moduleRef: string): Promise<ModuleDeletion>;
+    restoreModule(moduleRef: string): Promise<ModuleListItem>;
+    /** Irreversible: the version stays as a read-only record and its storage is returned. */
+    withdrawVersion(moduleRef: string, version: string): Promise<{
+        version: WithdrawnVersion;
+    }>;
+    /** Public catalogue route: never sends the credential, even when one is configured. */
+    listPublicVersions(moduleRef: string, query: {
+        page: number;
+        pageSize: number;
+        includeWithdrawn: boolean;
+    }): Promise<Page<PublicModuleVersion>>;
+    createVersion(moduleRef: string, body: CreateVersionBody): Promise<CreateVersionResult>;
+    requestUploadToken(moduleRef: string, version: string): Promise<UploadTicket>;
+    /**
+     * PUTs the JAR to the ticket URL. The ticket authenticates the upload, so no
+     * Authorization header is sent, and the URL must be on the configured API origin.
+     */
+    uploadJar(ticket: UploadTicket, bytes: Uint8Array): Promise<{
+        version: DevModuleVersion;
+    }>;
 }

package/dist/src/lib/api-client.js

@@ -1,83 +1,157 @@
+// Client for the UltiCloud machine API (contract: developer-client 1.0.0, copied
+// under tests/contract/). Success bodies are { data }, errors { error: { code, ... } }.
+import { assertAllowedApiUrl } from './config.js';
+export class ApiError extends Error {
+    status;
+    code;
+    requestId;
+    details;
+    constructor(status, code, message, requestId, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+        this.details = details;
+        this.name = 'ApiError';
+    }
+    /** Seconds to wait from details.retryAfterSeconds or the Retry-After header. */
+    get retryAfterSeconds() {
+        const value = this.details?.retryAfterSeconds;
+        return typeof value === 'number' ? value : undefined;
+    }
+}
 export class ApiClient {
-    baseUrl;
-    credentials;
-    constructor(credentials) {
-        this.credentials = credentials;
-        this.baseUrl = credentials.api_url;
-    }
-    static fromEnvOrCredentials(credentials) {
-        const envToken = process.env.ULTIKITS_TOKEN;
-        if (envToken) {
-            return new ApiClient({
-                type: 'access_token',
-                token: envToken,
-                api_url: 'https://api.ultikits.com',
-            });
-        }
-        if (credentials) {
-            return new ApiClient(credentials);
-        }
-        return null;
+    apiUrl;
+    credential;
+    constructor(options) {
+        this.apiUrl = assertAllowedApiUrl(options.apiUrl);
+        this.credential = options.credential ?? null;
     }
-    getHeaders() {
-        const headers = {};
-        if (this.credentials.type === 'oauth') {
-            headers['Authorization'] = `Bearer ${this.credentials.access_token}`;
-        }
-        else {
-            headers['X-Access-Token'] = this.credentials.token;
+    async request(method, path, body, opts = {}) {
+        const headers = { accept: 'application/json' };
+        if (opts.auth !== false) {
+            if (!this.credential)
+                throw new Error('No credential configured');
+            headers.authorization = `Bearer ${this.credential}`;
         }
-        return headers;
-    }
-    async get(path) {
-        const response = await fetch(`${this.baseUrl}${path}`, {
-            method: 'GET',
-            headers: this.getHeaders(),
-        });
-        return response.json();
-    }
-    async post(path, body) {
-        const headers = {
-            ...this.getHeaders(),
-            'Content-Type': 'application/json',
-        };
-        const response = await fetch(`${this.baseUrl}${path}`, {
-            method: 'POST',
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        const response = await fetch(`${this.apiUrl}${path}`, {
+            method,
             headers,
-            body: body ? JSON.stringify(body) : undefined,
+            body: body === undefined ? undefined : JSON.stringify(body),
+            redirect: 'error',
         });
-        return response.json();
-    }
-    async postMultipart(path, formData, extraHeaders) {
-        const headers = {
-            ...this.getHeaders(),
-            ...(extraHeaders ?? {}),
-        };
-        const response = await fetch(`${this.baseUrl}${path}`, {
-            method: 'POST',
-            headers,
-            body: formData,
+        return parseEnvelope(response);
+    }
+    // ---- device authorization (public, no credential) ----
+    deviceAuthorize(suggestedName) {
+        const body = { clientKind: 'cli' };
+        if (suggestedName)
+            body.suggestedName = suggestedName;
+        return this.request('POST', '/v1/device/authorize', body, { auth: false });
+    }
+    deviceToken(deviceCode) {
+        return this.request('POST', '/v1/device/token', { deviceCode }, { auth: false });
+    }
+    // ---- authenticated ----
+    whoami() {
+        return this.request('GET', '/v1/developer/whoami');
+    }
+    revokeCurrentCredential() {
+        return this.request('POST', '/v1/developer/credential/revoke');
+    }
+    createModule(body) {
+        return this.request('POST', '/v1/developer/modules', body);
+    }
+    listModules(query) {
+        const params = new URLSearchParams({ page: String(query.page), pageSize: String(query.pageSize) });
+        if (query.q !== undefined)
+            params.set('q', query.q);
+        return this.request('GET', `/v1/developer/modules?${params}`);
+    }
+    updateModule(moduleRef, body) {
+        return this.request('PATCH', `/v1/developer/modules/${encodeURIComponent(moduleRef)}`, body);
+    }
+    /** Recoverable delete: the module can be restored until `restorableUntil`. */
+    deleteModule(moduleRef) {
+        return this.request('DELETE', `/v1/developer/modules/${encodeURIComponent(moduleRef)}`);
+    }
+    restoreModule(moduleRef) {
+        return this.request('POST', `/v1/developer/modules/${encodeURIComponent(moduleRef)}/restore`);
+    }
+    /** Irreversible: the version stays as a read-only record and its storage is returned. */
+    withdrawVersion(moduleRef, version) {
+        return this.request('POST', `/v1/developer/modules/${encodeURIComponent(moduleRef)}/versions/${encodeURIComponent(version)}/withdraw`);
+    }
+    /** Public catalogue route: never sends the credential, even when one is configured. */
+    listPublicVersions(moduleRef, query) {
+        const params = new URLSearchParams({
+            page: String(query.page),
+            pageSize: String(query.pageSize),
+            includeWithdrawn: String(query.includeWithdrawn),
         });
-        return response.json();
-    }
-    async put(path, body) {
-        const headers = {
-            ...this.getHeaders(),
-            'Content-Type': 'application/json',
-        };
-        const response = await fetch(`${this.baseUrl}${path}`, {
-            method: 'PUT',
-            headers,
-            body: body ? JSON.stringify(body) : undefined,
+        return this.request('GET', `/v1/catalogue/modules/${encodeURIComponent(moduleRef)}/versions?${params}`, undefined, {
+            auth: false,
         });
-        return response.json();
     }
-    async delete(path) {
-        const response = await fetch(`${this.baseUrl}${path}`, {
-            method: 'DELETE',
-            headers: this.getHeaders(),
-        });
-        return response.json();
+    createVersion(moduleRef, body) {
+        return this.request('POST', `/v1/developer/modules/${encodeURIComponent(moduleRef)}/versions`, body);
+    }
+    requestUploadToken(moduleRef, version) {
+        return this.request('POST', `/v1/developer/modules/${encodeURIComponent(moduleRef)}/versions/${encodeURIComponent(version)}/upload-token`);
+    }
+    /**
+     * PUTs the JAR to the ticket URL. The ticket authenticates the upload, so no
+     * Authorization header is sent, and the URL must be on the configured API origin.
+     */
+    async uploadJar(ticket, bytes) {
+        let target;
+        try {
+            target = new URL(ticket.uploadUrl);
+        }
+        catch {
+            throw new Error('服务器返回的上传地址无效，已停止上传。');
+        }
+        if (target.origin !== new URL(this.apiUrl).origin) {
+            throw new Error(`上传地址 ${target.origin} 与 API 源站 ${new URL(this.apiUrl).origin} 不一致，已停止上传。`);
+        }
+        if (ticket.method !== 'PUT')
+            throw new Error(`上传票据的方法不是 PUT（${ticket.method}），已停止上传。`);
+        const headers = {};
+        for (const [name, value] of Object.entries(ticket.headers ?? {})) {
+            if (name.toLowerCase() !== 'authorization')
+                headers[name] = value;
+        }
+        headers['Content-Type'] = 'application/java-archive';
+        const body = bytes;
+        const response = await fetch(target, { method: 'PUT', headers, body, redirect: 'error' });
+        return parseEnvelope(response);
+    }
+}
+async function parseEnvelope(response) {
+    const text = await response.text();
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : undefined;
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (response.ok) {
+        if (parsed && typeof parsed === 'object' && 'data' in parsed)
+            return parsed.data;
+        throw new ApiError(response.status, 'unexpected_response', `服务器返回了无法识别的响应（HTTP ${response.status}）。`);
+    }
+    const error = parsed?.error;
+    if (error && typeof error.code === 'string') {
+        const details = { ...(error.details ?? {}) };
+        const retryAfter = Number(response.headers.get('retry-after'));
+        if (details.retryAfterSeconds === undefined && Number.isFinite(retryAfter) && retryAfter > 0) {
+            details.retryAfterSeconds = retryAfter;
+        }
+        return Promise.reject(new ApiError(response.status, error.code, String(error.message ?? error.code), error.requestId, details));
     }
+    throw new ApiError(response.status, 'unexpected_response', `服务器返回了无法识别的响应（HTTP ${response.status}）。`);
 }
 //# sourceMappingURL=api-client.js.map

package/dist/src/lib/command-errors.d.ts

@@ -0,0 +1,8 @@
+export type ManageOperation = 'list' | 'versions' | 'create' | 'update' | 'delete' | 'restore' | 'withdraw';
+export interface ErrorContext {
+    op: ManageOperation;
+    identifier?: string;
+    version?: string;
+    apiUrl: string;
+}
+export declare function describeCommandError(err: unknown, ctx: ErrorContext): string;

package/dist/src/lib/command-errors.js

@@ -0,0 +1,54 @@
+// Messages for the errors the modules / versions commands can receive
+// (tests/contract/developer-client/1.1.0/DEVELOPER-CLIENT.md, "错误码与客户端动作").
+import { ApiError } from './api-client.js';
+import { describeAuthError } from '../commands/whoami.js';
+const MANAGE_HINT = '此操作需要 manage 凭据：用 ultikits login 登录，或在开发者中心把开发者密钥轮换为管理作用域。';
+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('；');
+}
+function specific(err, ctx) {
+    const id = ctx.identifier ?? '';
+    switch (err.code) {
+        case 'key_scope_insufficient':
+            return MANAGE_HINT;
+        case 'rate_limited':
+            return `请求过于频繁，请 ${err.retryAfterSeconds ?? '稍'} 秒后再试（不会自动重试）。`;
+        case 'validation_failed':
+            return `参数不合格${fieldList(err) ? `：${fieldList(err)}` : '。'}`;
+        case 'not_found':
+            if (ctx.op === 'restore')
+                return `没有可恢复的模块 ${id}：标识符不对，或删除已超过 30 天恢复期。`;
+            if (ctx.op === 'withdraw')
+                return `模块 ${id} 或版本 ${ctx.version} 不存在，请检查标识符与版本号。`;
+            return `模块 ${id} 不存在，请检查标识符（用 ultikits modules list 查看你的模块）。`;
+        case 'version_not_published':
+            return `${id}@${ctx.version} 还在等待上传，不能撤回。`;
+        case 'module_identifier_taken':
+            if (ctx.op !== 'create')
+                return null;
+            return `标识符 ${id} 已被占用。若这是你 30 天内删除的模块，可用 ultikits modules restore ${id} 恢复。`;
+        case 'module_name_taken':
+            if (ctx.op !== 'create' && ctx.op !== 'update')
+                return null;
+            return '模块名称已被占用，请用 --name 换一个名称。';
+        default:
+            return null;
+    }
+}
+export function describeCommandError(err, ctx) {
+    if (err instanceof ApiError) {
+        const message = specific(err, ctx);
+        if (message) {
+            const req = err.requestId ? ` (requestId ${err.requestId})` : '';
+            return `${message} [${err.code}]${req}`;
+        }
+    }
+    // invalid_credential, role_required and anything unknown: same wording as whoami.
+    return describeAuthError(err, ctx.apiUrl);
+}
+//# sourceMappingURL=command-errors.js.map

package/dist/src/lib/config.d.ts

@@ -1,6 +1,43 @@
-import type { Credentials } from '../types.js';
+import type { CredentialKind, StoredCredential } from '../types.js';
+export declare const DEFAULT_API_URL = "https://api.ultikits.com";
+export declare const DEVELOPER_KEY_PATTERN: RegExp;
 export declare function getConfigDir(): string;
-export declare function readCredentials(configDir?: string): Credentials | null;
-export declare function writeCredentials(credentials: Credentials, configDir?: string): void;
+export type CredentialFileState = {
+    status: 'none';
+}
+/** A pre-UltiCloud file (type oauth / access_token) or one this version cannot read. */
+ | {
+    status: 'legacy';
+} | {
+    status: 'ok';
+    credential: StoredCredential;
+};
+export declare function readCredentials(configDir?: string): CredentialFileState;
+export declare function writeCredentials(credential: StoredCredential, configDir?: string): void;
 export declare function deleteCredentials(configDir?: string): void;
-export declare function getApiUrl(credentials: Credentials | null): string;
+/**
+ * Throws unless `url` is https, or plain http to a loopback host (test stubs).
+ * Returns the URL without a trailing slash.
+ */
+export declare function assertAllowedApiUrl(url: string): string;
+/** --api-url > ULTIKITS_API_URL > the credential file's apiUrl > production. */
+export declare function resolveApiUrl(flag: string | undefined, env: NodeJS.ProcessEnv, stored?: string): string;
+export declare function credentialKindOf(value: string): CredentialKind | null;
+export type ResolvedAuth = {
+    ok: true;
+    credential: string;
+    kind: CredentialKind;
+    apiUrl: string;
+    source: 'env' | 'file';
+} | {
+    ok: false;
+    message: string;
+};
+/** ULTIKITS_TOKEN wins over the credential file. Never sends anything. */
+export declare function resolveAuth(opts: {
+    apiUrl?: string;
+    env: NodeJS.ProcessEnv;
+    configDir?: string;
+}): ResolvedAuth;
+/** Developer centre URL for the known API hosts; null for any other host. */
+export declare function developerCentreUrl(apiUrl: string): string | null;

package/dist/src/lib/config.js

@@ -2,38 +2,117 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 const CREDENTIALS_FILE = 'credentials.json';
-const DEFAULT_API_URL = 'https://api.ultikits.com';
+export const DEFAULT_API_URL = 'https://api.ultikits.com';
+const CREDENTIAL_PATTERN = /^uc[cd]_[A-Za-z0-9_-]{43}$/;
+export const DEVELOPER_KEY_PATTERN = /^ucd_[A-Za-z0-9_-]{43}$/;
 export function getConfigDir() {
     return path.join(os.homedir(), '.ultikits');
 }
 export function readCredentials(configDir) {
-    const dir = configDir ?? getConfigDir();
-    const filePath = path.join(dir, CREDENTIALS_FILE);
+    const filePath = path.join(configDir ?? getConfigDir(), CREDENTIALS_FILE);
+    let content;
     try {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        return JSON.parse(content);
+        content = fs.readFileSync(filePath, 'utf-8');
     }
     catch {
-        return null;
+        return { status: 'none' };
     }
+    try {
+        const parsed = JSON.parse(content);
+        if (parsed &&
+            parsed.version === 2 &&
+            (parsed.kind === 'cli' || parsed.kind === 'developer') &&
+            typeof parsed.credential === 'string' &&
+            typeof parsed.apiUrl === 'string') {
+            return { status: 'ok', credential: parsed };
+        }
+    }
+    catch {
+        // fall through: unreadable file is treated like an old one
+    }
+    return { status: 'legacy' };
 }
-export function writeCredentials(credentials, configDir) {
+export function writeCredentials(credential, configDir) {
     const dir = configDir ?? getConfigDir();
-    fs.mkdirSync(dir, { recursive: true });
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     const filePath = path.join(dir, CREDENTIALS_FILE);
-    fs.writeFileSync(filePath, JSON.stringify(credentials, null, 2), { mode: 0o600 });
+    fs.writeFileSync(filePath, JSON.stringify(credential, null, 2) + '\n', { mode: 0o600 });
+    // writeFileSync keeps the mode of an existing file, so tighten it explicitly.
+    fs.chmodSync(filePath, 0o600);
 }
 export function deleteCredentials(configDir) {
-    const dir = configDir ?? getConfigDir();
-    const filePath = path.join(dir, CREDENTIALS_FILE);
     try {
-        fs.unlinkSync(filePath);
+        fs.unlinkSync(path.join(configDir ?? getConfigDir(), CREDENTIALS_FILE));
     }
     catch {
         // Already gone
     }
 }
-export function getApiUrl(credentials) {
-    return credentials?.api_url ?? DEFAULT_API_URL;
+/**
+ * Throws unless `url` is https, or plain http to a loopback host (test stubs).
+ * Returns the URL without a trailing slash.
+ */
+export function assertAllowedApiUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`API 地址无效：${url}`);
+    }
+    const loopback = parsed.hostname === '127.0.0.1' || parsed.hostname === 'localhost';
+    if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && loopback)) {
+        throw new Error(`API 地址必须使用 https（仅 127.0.0.1 与 localhost 可用 http）：${parsed.origin}`);
+    }
+    return url.replace(/\/+$/, '');
+}
+/** --api-url > ULTIKITS_API_URL > the credential file's apiUrl > production. */
+export function resolveApiUrl(flag, env, stored) {
+    return assertAllowedApiUrl(flag || env.ULTIKITS_API_URL || stored || DEFAULT_API_URL);
+}
+export function credentialKindOf(value) {
+    if (!CREDENTIAL_PATTERN.test(value))
+        return null;
+    return value.startsWith('ucc_') ? 'cli' : 'developer';
+}
+/** ULTIKITS_TOKEN wins over the credential file. Never sends anything. */
+export function resolveAuth(opts) {
+    const envToken = opts.env.ULTIKITS_TOKEN?.trim();
+    try {
+        if (envToken) {
+            const kind = credentialKindOf(envToken);
+            if (!kind) {
+                return { ok: false, message: 'ULTIKITS_TOKEN 不是 UltiCloud 凭据（应为 ucd_ 开发者密钥或 ucc_ CLI 凭据）。' };
+            }
+            return { ok: true, credential: envToken, kind, apiUrl: resolveApiUrl(opts.apiUrl, opts.env), source: 'env' };
+        }
+        const state = readCredentials(opts.configDir);
+        if (state.status === 'legacy') {
+            return { ok: false, message: '凭据文件是旧版格式，对新接口无效，请重新 ultikits login。' };
+        }
+        if (state.status === 'none') {
+            return { ok: false, message: '未登录：请运行 ultikits login，或设置环境变量 ULTIKITS_TOKEN。' };
+        }
+        const stored = state.credential;
+        return {
+            ok: true,
+            credential: stored.credential,
+            kind: stored.kind,
+            apiUrl: resolveApiUrl(opts.apiUrl, opts.env, stored.apiUrl),
+            source: 'file',
+        };
+    }
+    catch (err) {
+        return { ok: false, message: err.message };
+    }
+}
+/** Developer centre URL for the known API hosts; null for any other host. */
+export function developerCentreUrl(apiUrl) {
+    const host = new URL(apiUrl).hostname;
+    if (host === 'api.ultikits.com')
+        return 'https://panel.ultikits.com/developer';
+    if (host === 'api-staging.ultikits.com')
+        return 'https://panel-staging.ultikits.com/developer';
+    return null;
 }
 //# sourceMappingURL=config.js.map

package/dist/src/lib/confirm.d.ts

@@ -0,0 +1,22 @@
+export interface ConfirmOptions {
+    /** The string the user has to type, compared case-sensitively. */
+    expected: string;
+    /** Value of --confirm, when given. */
+    flagValue?: string;
+    /** -y / --yes was given. */
+    yes?: boolean;
+    /** stdin and stdout are a terminal. */
+    interactive: boolean;
+    /** What the operation does; shown before the question. */
+    warning: string;
+    /** Asks one question and returns the answer (tests pass a stub). */
+    ask?: (question: string) => Promise<string>;
+}
+export type ConfirmResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function requireConfirmation(options: ConfirmOptions): Promise<ConfirmResult>;
+export declare function isInteractiveTerminal(): boolean;

package/dist/src/lib/confirm.js

@@ -0,0 +1,47 @@
+// Confirmation for destructive commands (modules delete, versions withdraw).
+//
+// The user must type the exact target string: the module identifier, or
+// <identifier>@<version> for a withdrawal. On a terminal without -y the CLI asks
+// for it; otherwise --confirm <same string> is required. -y alone is never enough,
+// so a script that adds -y to every command cannot delete anything by accident.
+// Callers must check the result before sending any request.
+import readline from 'node:readline/promises';
+export async function requireConfirmation(options) {
+    const { expected, flagValue } = options;
+    if (flagValue !== undefined) {
+        if (flagValue === expected)
+            return { ok: true };
+        return { ok: false, reason: `--confirm 的值必须与 ${expected} 完全一致（区分大小写），未发送任何请求。` };
+    }
+    if (!options.interactive || options.yes) {
+        return {
+            ok: false,
+            reason: `非交互模式或使用了 -y 时，必须加 --confirm ${expected} 确认（单有 -y 不够），未发送任何请求。`,
+        };
+    }
+    const ask = options.ask ?? askOnTerminal;
+    let answer;
+    try {
+        answer = await ask(`${options.warning}\n请输入 ${expected} 确认（输入其他内容取消）：`);
+    }
+    catch {
+        // Ctrl-C / Ctrl-D: readline rejects (AbortError on Node 24); treat it as a cancel.
+        return { ok: false, reason: '已取消（输入被中断），未发送任何请求。' };
+    }
+    if (answer === expected)
+        return { ok: true };
+    return { ok: false, reason: `输入与 ${expected} 不一致，已取消，未发送任何请求。` };
+}
+export function isInteractiveTerminal() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+async function askOnTerminal(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=confirm.js.map

package/dist/src/lib/logger.d.ts

@@ -3,3 +3,9 @@ export declare function error(msg: string): void;
 export declare function info(msg: string): void;
 export declare function warn(msg: string): void;
 export declare function spinner(text: string): import("ora").Ora;
+/** Output sink for commands; tests pass a capturing one. */
+export interface Io {
+    out(msg: string): void;
+    err(msg: string): void;
+}
+export declare const consoleIo: Io;

package/dist/src/lib/logger.js

@@ -15,4 +15,8 @@ export function warn(msg) {
 export function spinner(text) {
     return ora({ text, color: 'cyan' });
 }
+export const consoleIo = {
+    out: (msg) => console.log(msg),
+    err: (msg) => console.error(msg),
+};
 //# sourceMappingURL=logger.js.map

package/dist/src/lib/mask.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Masked form of a credential for display: known prefix + first 4 + •••• + last 4.
+ * Anything that does not look like a UltiCloud credential is fully masked.
+ */
+export declare function maskCredential(value: string): string;
+/** Replaces every occurrence of `secret` in `text` with its masked form. */
+export declare function redact(text: string, secret: string | undefined | null): string;

package/dist/src/lib/mask.js

@@ -0,0 +1,18 @@
+/**
+ * Masked form of a credential for display: known prefix + first 4 + •••• + last 4.
+ * Anything that does not look like a UltiCloud credential is fully masked.
+ */
+export function maskCredential(value) {
+    const match = /^(uc[cdu]_)(.+)$/.exec(value);
+    if (!match || match[2].length < 12)
+        return '••••';
+    const body = match[2];
+    return `${match[1]}${body.slice(0, 4)}••••${body.slice(-4)}`;
+}
+/** Replaces every occurrence of `secret` in `text` with its masked form. */
+export function redact(text, secret) {
+    if (!secret)
+        return text;
+    return text.split(secret).join(maskCredential(secret));
+}
+//# sourceMappingURL=mask.js.map