@qmuse/qmuse-cli 1.0.0-dev.0

package/dist/cli.js

@@ -0,0 +1,719 @@
+#!/usr/bin/env node
+/**
+ * QMuse CLI —— 将本地 React 项目导入 QMuse。
+ *
+ * 用法见 `qmuse help`。
+ */
+import { applyEnvironment, loadConfig, saveConfig, findConfigPath } from './config.js';
+import { hasAuth } from './client.js';
+import { log } from './logger.js';
+import * as api from './api.js';
+import * as login from './login.js';
+import { prompt } from './login.js';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { createImportArchive } from './import/archive.js';
+import { configureAppImport, getAppOpenUrl, getImportStatusUrl, queryAppImportStatus, startAppImport, uploadImportArchive, } from './import/api.js';
+import { pollAppImport } from './import/poll.js';
+import { preflightImport } from './import/preflight.js';
+import { clearPendingImport, completeManagedImport, loadManagedProject, saveManagedProject, setPendingImport, } from './import/project.js';
+import { clearImportFailureDiagnostic, writeImportFailureDiagnostic, } from './import/diagnostic.js';
+import { checkCloudInit, CLOUD_INIT_SUCCESS_MESSAGE } from './cloud.js';
+import { QMUSE_CLI_VERSION } from './version.js';
+// ---------------- 参数解析 ----------------
+const BOOL_FLAGS = new Set([
+    '--help', '-h', '--version', '-V', '--json', '--status',
+    '--log', '--no-open', '--wait',
+    '--acknowledge-empty-cloud-data',
+    '--confirm-cloud-service',
+]);
+function parseArgs(argv) {
+    const command = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok.startsWith('--') || tok.startsWith('-')) {
+            const eq = tok.indexOf('=');
+            if (eq >= 0) {
+                const key = tok.slice(0, eq);
+                flags[key] = tok.slice(eq + 1);
+                continue;
+            }
+            if (BOOL_FLAGS.has(tok)) {
+                flags[tok] = true;
+                continue;
+            }
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                flags[tok] = true;
+            }
+            else {
+                flags[tok] = next;
+                i++;
+            }
+        }
+        else {
+            command.push(tok);
+        }
+    }
+    return { command, flags };
+}
+const str = (f, k) => {
+    const v = f[k];
+    return typeof v === 'string' ? v : undefined;
+};
+const num = (f, key, def) => {
+    const v = str(f, key);
+    const n = v === undefined ? def : Number(v);
+    return Number.isFinite(n) ? n : def;
+};
+/** 仅允许使用内置环境，避免命令行参数把登录凭证重定向到任意地址。 */
+function resolveCfg(flags) {
+    let cfg = loadConfig();
+    const environment = str(flags, '--env');
+    if (environment) {
+        if (!['prod', 'pre', 'local'].includes(environment)) {
+            fail('--env 仅支持 prod / pre / local');
+        }
+        cfg = applyEnvironment(cfg, environment);
+    }
+    // --space-id 覆盖当前空间
+    const sp = str(flags, '--space-id');
+    if (sp)
+        cfg.spaceId = sp;
+    return cfg;
+}
+/** 统一打印结果（code cat/diff 走纯文本，其余走 JSON）。 */
+function output(value, flags) {
+    if (typeof value === 'string') {
+        process.stdout.write(value.endsWith('\n') ? value : `${value}\n`);
+        return;
+    }
+    const json = flags['--json'] === true ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+    process.stdout.write(`${json}\n`);
+}
+function fail(message) {
+    log.error(message);
+    process.exit(1);
+}
+function requireAuth(cfg) {
+    if (!hasAuth(cfg)) {
+        fail('当前环境未登录。请先运行 `qmuse login`。');
+    }
+}
+function readPublicConfig(value) {
+    if (!value)
+        return {};
+    const raw = value.startsWith('@')
+        ? readFileSync(value.slice(1), 'utf8')
+        : value;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`--public-config 不是有效 JSON：${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('--public-config 必须是字符串键值对象');
+    }
+    const config = {};
+    for (const [key, item] of Object.entries(parsed)) {
+        if (typeof item !== 'string') {
+            throw new Error(`--public-config 的 ${key} 必须是字符串`);
+        }
+        config[key] = item;
+    }
+    return config;
+}
+function parseImportCloudMode(value) {
+    const normalized = (value || 'AUTO').toUpperCase();
+    if (!['AUTO', 'EXTERNAL', 'QMUSE'].includes(normalized)) {
+        throw new Error('--cloud-mode 仅支持 AUTO / EXTERNAL / QMUSE');
+    }
+    return normalized;
+}
+function printImportStatus(status, flags) {
+    if (flags['--json'] === true) {
+        output(status, flags);
+        return;
+    }
+    log.info(`${status.status}${status.stage ? ` / ${status.stage}` : ''}${status.message ? `：${status.message}` : ''}`);
+    if (status.failureDiagnostic) {
+        log.warn(`失败分类：${status.failureDiagnostic.category}`);
+        log.warn(status.failureDiagnostic.summary);
+        const items = Array.isArray(status.failureDiagnostic.items)
+            ? status.failureDiagnostic.items
+            : [];
+        for (const item of items.slice(0, 10)) {
+            const location = item.file
+                ? `${item.file}${item.line ? `:${item.line}${item.column ? `:${item.column}` : ''}` : ''}`
+                : '';
+            log.warn(`${location ? `${location} ` : ''}${item.code ? `${item.code} ` : ''}${item.message}`);
+        }
+        const mismatch = status.failureDiagnostic.sourceMismatch;
+        if (mismatch) {
+            log.warn(`源码指纹：期望 ${mismatch.expectedHash ?? '(未知)'}，实际 ${mismatch.actualHash ?? '(未知)'}`);
+            for (const [label, paths] of [
+                ['缺少文件', mismatch.missingFiles],
+                ['多余文件', mismatch.unexpectedFiles],
+                ['内容变化', mismatch.changedFiles],
+            ]) {
+                if (paths.length)
+                    log.warn(`${label}：${paths.join(', ')}`);
+            }
+        }
+    }
+    else if (status.diagnostic) {
+        log.warn(status.diagnostic);
+    }
+}
+async function pollImportWithLogs(jobId, cfg, flags) {
+    const abortController = new AbortController();
+    const onInterrupt = () => abortController.abort();
+    process.once('SIGINT', onInterrupt);
+    let lastStage = '';
+    try {
+        return await pollAppImport(() => queryAppImportStatus(jobId, cfg), {
+            signal: abortController.signal,
+            onStatus: status => {
+                if (flags['--json'] === true)
+                    return;
+                const stage = `${status.status}:${status.stage ?? ''}`;
+                if (stage === lastStage)
+                    return;
+                lastStage = stage;
+                log.info(status.message || status.stage || status.status);
+            },
+        });
+    }
+    finally {
+        process.removeListener('SIGINT', onInterrupt);
+    }
+}
+async function resolveImportConfiguration(status, cfg, flags) {
+    if (status.stage === 'QMUSE_CLOUD_ADAPTATION_REQUIRED')
+        return undefined;
+    const interactive = process.stdin.isTTY === true && flags['--json'] !== true;
+    let cloudMode = parseImportCloudMode(str(flags, '--cloud-mode'));
+    if (cloudMode === 'AUTO') {
+        if (!interactive)
+            return undefined;
+        const answer = (await prompt('检测到云服务依赖，保留外部服务还是使用 QMuse 云服务？[external/qmuse]：'))
+            .trim().toLowerCase();
+        cloudMode = answer === 'qmuse' ? 'QMUSE' : 'EXTERNAL';
+    }
+    const publicConfig = readPublicConfig(str(flags, '--public-config'));
+    if (cloudMode === 'EXTERNAL') {
+        for (const key of status.requiredConfigKeys ?? []) {
+            if (publicConfig[key]?.trim())
+                continue;
+            if (!interactive)
+                return undefined;
+            publicConfig[key] = await prompt(`请输入公开构建配置 ${key}：`);
+            if (!publicConfig[key]?.trim())
+                return undefined;
+        }
+    }
+    let acknowledgeEmptyCloudData = flags['--acknowledge-empty-cloud-data'] === true;
+    let confirmCloudService = flags['--confirm-cloud-service'] === true;
+    if (cloudMode === 'QMUSE' && status.sourceScenario === 'QMUSE_TEMPLATE') {
+        if (!confirmCloudService) {
+            if (!interactive)
+                return undefined;
+            const answer = await prompt('确认开通并同步源码声明的 QMuse 云服务资源？[y/N]：');
+            confirmCloudService = /^y(?:es)?$/iu.test(answer);
+            if (!confirmCloudService)
+                return undefined;
+        }
+    }
+    else if (cloudMode === 'QMUSE' && !acknowledgeEmptyCloudData) {
+        if (!interactive)
+            return undefined;
+        const answer = await prompt('确认不会自动迁移外部服务中的存量业务数据？[y/N]：');
+        acknowledgeEmptyCloudData = /^y(?:es)?$/iu.test(answer);
+        if (!acknowledgeEmptyCloudData)
+            return undefined;
+    }
+    const configured = await configureAppImport({
+        jobId: status.jobId,
+        cloudMode,
+        ...(cloudMode === 'EXTERNAL' ? { publicConfig } : {}),
+        ...(cloudMode === 'QMUSE' ? { acknowledgeEmptyCloudData } : {}),
+        ...(cloudMode === 'QMUSE' && confirmCloudService
+            ? { confirmCloudService }
+            : {}),
+    }, cfg);
+    if (!configured.ok || !configured.data) {
+        throw new Error(`提交导入配置失败：${configured.errorMessage ?? configured.errorCode ?? `HTTP ${configured.status}`}`);
+    }
+    return configured.data;
+}
+async function finishImport(status, sourceHash, cfg, flags, managedProject, rootDir) {
+    if (status.status !== 'READY' || !status.appId || !status.versionId) {
+        if (flags['--json'] === true) {
+            output({ success: false, ...status }, flags);
+        }
+        else {
+            printImportStatus(status, flags);
+            if (status.status === 'FAILED')
+                log.error('导入失败');
+            else
+                log.warn(`任务需要继续配置，可执行 qmuse import status ${status.jobId} --wait`);
+        }
+        process.exitCode = status.status === 'FAILED' ? 1 : 2;
+        if (status.status === 'FAILED' && rootDir) {
+            const diagnosticPath = await writeImportFailureDiagnostic({ rootDir, status });
+            if (flags['--json'] !== true) {
+                log.warn(`诊断已写入 ${diagnosticPath}`);
+                if (status.failureDiagnostic?.fixableByModel) {
+                    log.warn(`请让当前大模型读取 ${diagnosticPath}，修复源码后执行 qmuse import .`);
+                }
+            }
+        }
+        if (status.status === 'FAILED' && managedProject) {
+            clearPendingImport(managedProject, status.jobId);
+            await saveManagedProject(managedProject);
+        }
+        return;
+    }
+    const openUrl = getAppOpenUrl(cfg.webBaseUrl, status.appId);
+    const pending = managedProject?.manifest.pendingImports?.[managedProject.environment];
+    const completedSourceHash = sourceHash || pending?.sourceHash;
+    const completedSpaceId = pending?.spaceId || managedProject?.target?.spaceId || cfg.spaceId;
+    if (managedProject) {
+        if (!completedSourceHash || !completedSpaceId) {
+            throw new Error('导入已完成，但本地项目绑定缺少 sourceHash 或 spaceId');
+        }
+        completeManagedImport(managedProject, {
+            apiBaseUrl: cfg.baseUrl,
+            appId: status.appId,
+            jobId: status.jobId,
+            sourceHash: completedSourceHash,
+            spaceId: completedSpaceId,
+            versionId: status.versionId,
+        });
+        await saveManagedProject(managedProject);
+    }
+    if (rootDir)
+        await clearImportFailureDiagnostic(rootDir);
+    const result = {
+        success: true,
+        jobId: status.jobId,
+        appId: status.appId,
+        chatId: status.chatId,
+        sprintId: status.sprintId,
+        versionId: status.versionId,
+        openUrl,
+        sourceHash: completedSourceHash,
+        operation: status.operation || pending?.operation || (managedProject?.target ? 'UPDATE' : 'CREATE'),
+        templateCommit: status.templateCommit,
+        importerVersion: status.importerVersion,
+        assetCount: status.assetCount,
+        uploadedAssetCount: status.uploadedAssetCount,
+        bundledAssetCount: status.bundledAssetCount,
+        contentSafetyStatus: status.contentSafetyStatus,
+        cloudMode: status.cloudMode,
+    };
+    if (flags['--json'] === true)
+        output(result, flags);
+    else {
+        log.success('项目检查、内容安全、预览和发布产物均已通过');
+        log.success('导入成功');
+        log.raw(`${openUrl}\n`);
+    }
+    if (flags['--no-open'] !== true) {
+        const opened = await login.openBrowser(openUrl);
+        if (!opened && flags['--json'] !== true)
+            log.warn('无法自动打开浏览器');
+    }
+}
+async function cmdImport(command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const subcommand = command[1];
+    if (subcommand === 'status') {
+        const jobId = command[2];
+        if (!jobId)
+            fail('用法: qmuse import status <jobId> [--wait]');
+        if (flags['--wait'] === true) {
+            const candidateManagedProject = await loadManagedProject(process.cwd(), cfg, str(flags, '--env'));
+            const pendingImport = candidateManagedProject
+                ?.manifest.pendingImports?.[candidateManagedProject.environment];
+            if (pendingImport &&
+                pendingImport.jobId !== jobId) {
+                throw new Error('当前项目记录的待恢复任务与指定 jobId 不一致');
+            }
+            const managedProject = pendingImport ? candidateManagedProject : undefined;
+            const polled = await pollImportWithLogs(jobId, cfg, flags);
+            if (!polled.status) {
+                log.warn(`已停止本地等待，可继续执行 qmuse import status ${jobId} --wait`);
+                process.exitCode = 130;
+                return;
+            }
+            await finishImport(polled.status, undefined, cfg, flags, managedProject, process.cwd());
+        }
+        else {
+            const result = await queryAppImportStatus(jobId, cfg);
+            if (!result.ok || !result.data) {
+                fail(`查询导入任务失败：${result.errorMessage ?? result.errorCode ?? `HTTP ${result.status}`}`);
+            }
+            printImportStatus(result.data, flags);
+        }
+        return;
+    }
+    if (subcommand === 'configure') {
+        const jobId = command[2];
+        if (!jobId)
+            fail('用法: qmuse import configure <jobId> --cloud-mode EXTERNAL|QMUSE');
+        const mode = parseImportCloudMode(str(flags, '--cloud-mode'));
+        if (mode === 'AUTO')
+            fail('configure 必须指定 --cloud-mode EXTERNAL 或 QMUSE');
+        const result = await configureAppImport({
+            jobId,
+            cloudMode: mode,
+            ...(mode === 'EXTERNAL'
+                ? { publicConfig: readPublicConfig(str(flags, '--public-config')) }
+                : flags['--confirm-cloud-service'] === true
+                    ? { confirmCloudService: true }
+                    : { acknowledgeEmptyCloudData: flags['--acknowledge-empty-cloud-data'] === true }),
+        }, cfg);
+        if (!result.ok || !result.data) {
+            fail(`提交导入配置失败：${result.errorMessage ?? result.errorCode ?? `HTTP ${result.status}`}`);
+        }
+        printImportStatus(result.data, flags);
+        return;
+    }
+    const directory = subcommand;
+    if (!directory)
+        fail('用法: qmuse import <directory> [--space-id <id>]');
+    const rootDir = path.resolve(directory);
+    await clearImportFailureDiagnostic(rootDir);
+    const managedProject = await loadManagedProject(rootDir, cfg, str(flags, '--env'));
+    const explicitSpaceId = str(flags, '--space-id');
+    const operation = managedProject?.target ? 'UPDATE' : 'CREATE';
+    if (managedProject?.target &&
+        explicitSpaceId &&
+        explicitSpaceId !== managedProject.target.spaceId) {
+        throw new Error('更新导入不能切换目标空间；--space-id 必须与项目绑定一致');
+    }
+    const spaceId = explicitSpaceId ||
+        managedProject?.target?.spaceId ||
+        managedProject?.manifest.defaultSpaceId ||
+        cfg.spaceId;
+    if (!spaceId)
+        fail('请通过 --space-id 指定目标空间，或先执行 qmuse space use <spaceId>');
+    const cloudMode = parseImportCloudMode(str(flags, '--cloud-mode'));
+    if (flags['--json'] !== true)
+        log.info('正在只读预检本地仓库...');
+    const preflight = await preflightImport(directory);
+    if (managedProject?.target?.lastSourceHash === preflight.sourceHash) {
+        const result = {
+            success: true,
+            noChanges: true,
+            operation: 'UPDATE',
+            appId: managedProject.target.appId,
+            versionId: managedProject.target.lastVersionId,
+            sourceHash: preflight.sourceHash,
+            openUrl: getAppOpenUrl(cfg.webBaseUrl, managedProject.target.appId),
+        };
+        if (flags['--json'] === true)
+            output(result, flags);
+        else
+            log.success('源码没有变化，无需创建新版本');
+        return;
+    }
+    if (flags['--json'] !== true) {
+        log.success(`识别为 React 项目（${preflight.fileCount} 个文件）`);
+        if (flags['--log'] === true) {
+            log.dim(`源码 SHA-256：${preflight.sourceHash}`);
+            log.dim(`静态资源：${preflight.assets.length} 个`);
+            log.dim(`公开配置键：${preflight.envKeys.join(', ') || '(无)'}`);
+            log.dim(`云服务：${preflight.cloudProviders.join(', ') || '(无)'}`);
+            log.dim(`状态接口：${getImportStatusUrl(cfg)}`);
+        }
+        log.info('正在打包并上传源码...');
+    }
+    const archive = await createImportArchive(preflight);
+    let sourceToken;
+    try {
+        sourceToken = await uploadImportArchive({
+            filePath: archive.filePath,
+            spaceId,
+        }, cfg);
+    }
+    finally {
+        await archive.cleanup();
+    }
+    if (flags['--json'] !== true)
+        log.success('源代码上传完成');
+    const started = await startAppImport({
+        sourceToken,
+        spaceId,
+        title: str(flags, '--title') || preflight.title,
+        sourceHash: preflight.sourceHash,
+        sourceType: 'REACT_VITE',
+        cloudMode,
+        idempotencyKey: str(flags, '--idempotency-key'),
+        sourceScenario: managedProject ? 'QMUSE_TEMPLATE' : 'EXTERNAL_REPOSITORY',
+        operation,
+        ...(managedProject?.target
+            ? {
+                targetAppId: managedProject.target.appId,
+                baseVersionId: managedProject.target.lastVersionId,
+            }
+            : {}),
+    }, cfg);
+    if (!started.ok || !started.data?.jobId) {
+        throw new Error(`创建导入任务失败：${started.errorMessage ?? started.errorCode ?? `HTTP ${started.status}`}`);
+    }
+    const jobId = started.data.jobId;
+    if (managedProject) {
+        setPendingImport(managedProject, {
+            apiBaseUrl: cfg.baseUrl,
+            jobId,
+            operation,
+            sourceHash: preflight.sourceHash,
+            spaceId,
+            createdAt: new Date().toISOString(),
+        });
+        await saveManagedProject(managedProject);
+    }
+    if (flags['--json'] !== true)
+        log.success(`已创建导入任务 ${jobId}`);
+    let polled = await pollImportWithLogs(jobId, cfg, flags);
+    while (polled.reason === 'CONFIGURATION_REQUIRED' && polled.status) {
+        const configured = await resolveImportConfiguration(polled.status, cfg, flags);
+        if (!configured) {
+            await finishImport(polled.status, preflight.sourceHash, cfg, flags, managedProject, rootDir);
+            return;
+        }
+        polled = await pollImportWithLogs(jobId, cfg, flags);
+    }
+    if (!polled.status) {
+        if (flags['--json'] === true) {
+            output({ success: false, interrupted: true, jobId }, flags);
+        }
+        else {
+            log.warn(`已停止本地等待，服务端任务仍会继续；使用 qmuse import status ${jobId} --wait 恢复查询`);
+        }
+        process.exitCode = 130;
+        return;
+    }
+    await finishImport(polled.status, preflight.sourceHash, cfg, flags, managedProject, rootDir);
+}
+async function cmdCloud(command, flags) {
+    const subcommand = command[1];
+    if (subcommand !== 'init') {
+        fail(`未知 cloud 子命令: ${subcommand ?? '(空)'}。可用: init`);
+    }
+    if (!str(flags, '-d')?.trim()) {
+        fail('用法: qmuse cloud init -d "<应用功能描述>"');
+    }
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const result = await checkCloudInit(process.cwd(), cfg, str(flags, '--env'));
+    if (flags['--json'] === true) {
+        output({ success: true, ...result }, flags);
+        return;
+    }
+    process.stdout.write(`${CLOUD_INIT_SUCCESS_MESSAGE}\n`);
+}
+// ---------------- 命令实现 ----------------
+async function cmdWhoami(flags) {
+    const cfg = resolveCfg(flags);
+    if (flags['--json'] === true) {
+        output({
+            apiBaseUrl: `${cfg.baseUrl}${cfg.apiPrefix || ''}`,
+            loggedIn: hasAuth(cfg),
+            ...(cfg.spaceId ? { spaceId: cfg.spaceId } : {}),
+        }, flags);
+        return;
+    }
+    log.info(`QMuse API: ${cfg.baseUrl}${cfg.apiPrefix || ''}`);
+    log.info(`登录状态 : ${hasAuth(cfg) ? '已登录' : '未登录'}`);
+    if (cfg.spaceId)
+        log.info(`当前空间 : ${cfg.spaceId}`);
+}
+async function cmdConfig(command, flags) {
+    const sub = command[1];
+    if (!sub || sub === 'get') {
+        const cfg = loadConfig();
+        const redacted = {
+            ...cfg,
+            sessionId: cfg.sessionId ? `<已设置，长度${cfg.sessionId.length}>` : '',
+            credentialOrigin: cfg.credentialOrigin || '',
+        };
+        output(redacted, flags);
+        return;
+    }
+    if (sub === 'path') {
+        output({ path: findConfigPath() ?? '(无配置文件，使用默认值)' }, flags);
+        return;
+    }
+    fail(`未知 config 子命令: ${sub}`);
+}
+async function cmdSpace(command, flags) {
+    const cfg = resolveCfg(flags);
+    const sub = command[1];
+    requireAuth(cfg);
+    if (sub === 'list') {
+        const r = await api.listSpaces(num(flags, '--page-index', 1), num(flags, '--page-size', 20), cfg);
+        if (!r.ok || !r.data)
+            fail(`查询空间失败: ${r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}`}`);
+        if (flags['--json'] === true) {
+            output(r.data, flags);
+            return;
+        }
+        const list = r.data.list ?? [];
+        log.info(`共 ${r.data.total} 个空间：`);
+        list.forEach((sp, i) => {
+            const pin = sp.isPinned ? '★' : ' ';
+            log.raw(`${String(i + 1).padStart(2)} ${pin} ${sp.cnName}  [${sp.spaceId}]${sp.role ? ' (' + sp.role + ')' : ''}\n`);
+        });
+        return;
+    }
+    if (sub === 'use' || sub === 'select') {
+        const spaceId = command[2] || str(flags, '--space-id');
+        if (!spaceId)
+            fail('用法: qmuse space use <spaceId>');
+        const next = { ...loadConfig(), spaceId };
+        saveConfig(next, true);
+        log.success(`已设为当前空间 spaceId=${spaceId}（后续请求带 x-space-id 头）`);
+        return;
+    }
+    if (sub === 'info') {
+        const r = await api.spaceInfo(cfg);
+        if (!r.ok)
+            fail(`查询当前空间失败: ${r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}`}`);
+        output(r.data, flags);
+        return;
+    }
+    fail(`未知 space 子命令: ${sub ?? '(空)'}。可用: list / use <spaceId> / info`);
+}
+async function cmdLogin(flags) {
+    const cfg = resolveCfg(flags);
+    if (flags['--status'] === true) {
+        const out = await login.loginStatus(cfg);
+        if (out.success)
+            log.success(out.message ?? '会话有效');
+        else
+            log.error(out.message ?? '会话无效');
+        return;
+    }
+    log.info(`登录方式：browser    目标：${cfg.baseUrl}${cfg.apiPrefix || ''}`);
+    const out = await login.loginBrowser(cfg, {
+        logRequestDetails: flags['--log'] === true,
+    });
+    if (out.success) {
+        login.closePrompt();
+        log.success(`登录成功（${out.method}）`);
+        if (flags['--json'] === true)
+            output({ success: true, method: out.method }, flags);
+    }
+    else {
+        login.closePrompt();
+        fail(out.message ?? '登录失败');
+    }
+}
+async function cmdLogout(flags) {
+    const cfg = resolveCfg(flags);
+    if (!(cfg.sessionId || '').trim()) {
+        log.warn('当前未配置登录态，无需退出');
+        return;
+    }
+    const cleared = { ...cfg, sessionId: '', credentialOrigin: '' };
+    const path = saveConfig(cleared, true);
+    log.success(`已清除登录态并写入 ${path}`);
+}
+// ---------------- 帮助 & 入口 ----------------
+const HELP = `QMuse CLI —— 将本地 React 项目导入 QMuse
+
+用法:
+  qmuse [global flags] <command> [subcommand] [flags]
+
+全局 flags:
+  --env <env>           环境预设：prod / pre / local
+  --json                结果以 JSON 输出
+  --log                 打印登录调试 URL 和临时 token（仅 browser 登录）
+
+  全局 flags 可放在命令前或命令后
+
+命令:
+  whoami                                            查看当前环境、登录和空间状态
+  login [--status] [--log] [--json]                 通过 QMuse 网页登录
+  logout                                            清除保存的登录态
+  config [get|path]                                 查看配置
+
+  cloud init -d "<应用功能描述>"                    校验当前空间的 QMuse 云服务权益
+
+  import <directory> [--space-id <id>]             导入本地 React 仓库
+      [--title <title>] [--cloud-mode AUTO|EXTERNAL|QMUSE]
+      [--public-config '<json>'|@file] [--acknowledge-empty-cloud-data]
+      [--confirm-cloud-service]
+      [--no-open] [--json] [--log]
+  import status <jobId> [--wait] [--no-open]        查询或恢复等待导入任务
+  import configure <jobId> --cloud-mode <mode>      补充云服务配置后继续任务
+
+  space list                                        我加入的空间列表
+  space use <spaceId>                               设为当前空间（后续带 x-space-id 头）
+  space info                                        当前空间信息
+
+典型流程:
+  qmuse login
+  qmuse space list
+  qmuse space use S640459450135
+  qmuse import /path/to/react-vite-app
+`;
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0) {
+        process.stdout.write(HELP);
+        return;
+    }
+    const { command, flags } = parseArgs(argv);
+    if (flags['--help'] === true || flags['-h'] === true) {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (flags['--version'] === true || flags['-V'] === true) {
+        process.stdout.write(`qmuse ${QMUSE_CLI_VERSION}\n`);
+        return;
+    }
+    const root = command[0];
+    try {
+        switch (root) {
+            case 'whoami':
+                await cmdWhoami(flags);
+                return;
+            case 'login':
+                await cmdLogin(flags);
+                return;
+            case 'logout':
+                await cmdLogout(flags);
+                return;
+            case 'config':
+                await cmdConfig(command, flags);
+                return;
+            case 'cloud':
+                await cmdCloud(command, flags);
+                return;
+            case 'import':
+                await cmdImport(command, flags);
+                return;
+            case 'space':
+                await cmdSpace(command, flags);
+                return;
+            case 'help':
+                process.stdout.write(HELP);
+                return;
+            default:
+                fail(`未知命令: ${root ?? '(空)'}。\n\n${HELP}`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        fail(msg);
+    }
+}
+main();