@qmuse/qmuse-cli 1.0.2-dev.1 → 1.0.3-dev.0

package/README.md

@@ -52,6 +52,8 @@ qmuse import /path/to/react-project --space-id <spaceId>
 
 从 QMuse 下载的项目，在项目根目录执行 `qmuse import .` 即可更新对应应用；没有关联应用时会创建新应用。普通外部项目每次导入都会创建新应用。
 
+平台已有新版本时，终端会询问是否用本地全部源码覆盖，不会自动合并平台修改。确认覆盖可执行 `qmuse import . --force`；脚本或 `--json` 模式须显式指定该参数。覆盖会在原应用创建新版本，仍需通过正常导入校验。
+
 ### 外部云服务
 
 ```bash
@@ -81,6 +83,36 @@ qmuse import configure <jobId> --cloud-mode EXTERNAL \
 
 本地等待中断不会取消任务。回到原项目目录，使用 `status <jobId> --wait` 继续等待；任务提示需要补充云服务配置时，使用 `configure`。
 
+## 本地云联调
+
+需要 Node.js 20.19+（或满足项目 Vite 的版本要求）、已安装依赖的 QMuse 模板、一次成功导入和 READY 云后端。首次需要云服务时，先生成最小业务代码与真实 Schema 并导入，再启动：
+
+```bash
+qmuse dev . --port 5173
+```
+
+命令使用项目自己的 Vite 和配置，监听 `127.0.0.1`。端口占用时自动选择可用端口，以终端打印的 URL 为准。`--env prod|pre|local` 选择 QMuse 平台环境；云资源固定为对应应用的开发环境。终端打印应用、用户和后端版本；单环境应用可能与正式页面共用数据。
+
+CLI 获取服务端解析的公开云配置，复用 Vite 的 `MUSE_RUNTIME_CONFIG_PATH` 注入机制。配置放在系统临时目录，退出时删除。Token 按需获取且不落盘，CLI 登录凭据不交给页面。数据库、文件和函数请求由浏览器通过用户 Session 直接访问云端，不使用管理 API Key 或 Dev Key。
+
+新版云服务资产已接入适配。旧项目在 `src/services/appwrite.ts` 的 `createQmuseAppwriteRuntime({ ... })` 参数中增加：
+
+```ts
+fetch: import.meta.env.DEV
+  ? (window as Window & {
+      __QMUSE_LOCAL_DEV__?: { fetch: typeof globalThis.fetch };
+    }).__QMUSE_LOCAL_DEV__?.fetch
+  : undefined,
+```
+
+不修改 SDK。只有 `qmuse dev` 注入本地 fetch；普通 `npm run dev` 和线上运行继续使用默认行为。生产构建移除本地适配分支。服务端必须先部署 `/api/appwrite/local-dev/context` 和 `/api/appwrite/local-dev/mutation-events`；缺少接口时不会降级为模拟云服务。
+
+页面改动热更新，Schema/函数改动继续执行 `qmuse import .`。导入更新本地绑定后，连接会重新获取配置并刷新页面。切换登录账号或应用绑定需重启连接；退出 CLI 不会自动撤销浏览器已经建立的 AppBase Session。SDK 的匿名降级行为保持不变，验收必须检查实际 Session 用户，不能只看页面是否显示。
+
+联调验收包括 CRUD、刷新读回、文件上传/预览、函数调用和权限拒绝；浏览器 Cookie 限制需在目标浏览器验证。`.muse-tmp`、`.qmuse` 和系统临时配置不进入导入包。
+
+研发验证：`npm test`、`npm run build`。浏览器集成测试使用已安装依赖的模板与相邻 `qmuse-cloud` 源仓库，运行 `QMUSE_DEV_TEMPLATE_ROOT=/path/to/installed-template npm run test:browser`，需本机 Chrome；测试中的云接口是隔离模拟后端，不代表真实云验收。
+
 ## 更多命令
 
 运行 `qmuse help` 查看完整命令和参数，运行 `qmuse --version` 查看版本。

package/dist/cli.js

@@ -16,14 +16,16 @@ 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 { resolveUpdateBase } from './import/update.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';
+import { startDevelopment } from './dev/index.js';
 // ---------------- 参数解析 ----------------
 const BOOL_FLAGS = new Set([
     '--help', '-h', '--version', '-V', '--json', '--status',
-    '--log', '--no-open', '--wait',
+    '--log', '--no-open', '--wait', '--force',
     '--acknowledge-empty-cloud-data',
     '--confirm-cloud-service',
 ]);
@@ -389,6 +391,9 @@ async function cmdImport(command, flags) {
     const managedProject = await loadManagedProject(rootDir, cfg, str(flags, '--env'));
     const explicitSpaceId = str(flags, '--space-id');
     const operation = managedProject?.target ? 'UPDATE' : 'CREATE';
+    if (flags['--force'] === true && !managedProject?.target) {
+        throw new Error('--force 仅用于更新已关联的应用，请先确认项目的应用绑定');
+    }
     if (managedProject?.target &&
         explicitSpaceId &&
         explicitSpaceId !== managedProject.target.spaceId) {
@@ -404,7 +409,16 @@ async function cmdImport(command, flags) {
     if (flags['--json'] !== true)
         log.info('正在只读预检本地仓库...');
     const preflight = await preflightImport(directory);
-    if (managedProject?.target?.lastSourceHash === preflight.sourceHash) {
+    const updateBase = managedProject?.target
+        ? await resolveUpdateBase({
+            target: managedProject.target,
+            cfg,
+            force: flags['--force'] === true,
+            interactive: process.stdin.isTTY === true && flags['--json'] !== true,
+            prompt,
+        })
+        : undefined;
+    if (managedProject?.target?.lastSourceHash === preflight.sourceHash && !updateBase?.remoteChanged) {
         const result = {
             success: true,
             noChanges: true,
@@ -457,7 +471,7 @@ async function cmdImport(command, flags) {
         ...(managedProject?.target
             ? {
                 targetAppId: managedProject.target.appId,
-                baseVersionId: managedProject.target.lastVersionId,
+                baseVersionId: updateBase.baseVersionId,
             }
             : {}),
     }, cfg);
@@ -517,6 +531,41 @@ async function cmdCloud(command, flags) {
     process.stdout.write(`${CLOUD_INIT_SUCCESS_MESSAGE}\n`);
 }
 // ---------------- 命令实现 ----------------
+async function cmdDev(command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    if (flags['--port'] !== undefined && typeof flags['--port'] !== 'string')
+        fail('--port 需要端口号');
+    const port = flags['--port'] === undefined ? 5173 : Number(str(flags, '--port'));
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        fail('--port 必须为 1 到 65535 的整数');
+    const development = await startDevelopment({
+        root: command[1] || process.cwd(), cfg,
+        environment: str(flags, '--env'),
+        port,
+    });
+    if (flags['--json'] === true) {
+        output({ success: true, appId: development.context.appId, userId: development.context.user.userId,
+            backendVersionId: development.context.backendVersionId, mode: development.context.mode,
+            urls: development.server.resolvedUrls?.local,
+        }, flags);
+    }
+    else {
+        log.info(`本地云连接：appId=${development.context.appId}，用户=${development.context.user.userId}，后端版本=${development.context.backendVersionId}`);
+        if (development.context.mode === 'SINGLE_ENV')
+            log.warn('当前为单环境应用，开发云资源可能与正式页面共用。');
+        development.server.printUrls();
+    }
+    await new Promise(resolve => {
+        const stop = () => {
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
+            void development.close().finally(resolve);
+        };
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+    });
+}
 async function cmdWhoami(flags) {
     const cfg = resolveCfg(flags);
     if (flags['--json'] === true) {
@@ -642,9 +691,10 @@ const HELP = `QMuse CLI —— 将本地 React 项目导入 QMuse
   config [get|path]                                 查看配置
 
   cloud init -d "<应用功能描述>"                    校验当前空间的 QMuse 云服务权益
+  dev [directory] [--port <port>]                   连接已导入应用的开发云资源并启动本地 Vite
 
   import <directory> [--space-id <id>]             导入本地 React 仓库
-      [--title <title>] [--cloud-mode AUTO|EXTERNAL|QMUSE]
+      [--title <title>] [--force] [--cloud-mode AUTO|EXTERNAL|QMUSE]
       [--public-config '<json>'|@file] [--acknowledge-empty-cloud-data]
       [--confirm-cloud-service]
       [--no-open] [--json] [--log]
@@ -694,6 +744,9 @@ async function main() {
             case 'cloud':
                 await cmdCloud(command, flags);
                 return;
+            case 'dev':
+                await cmdDev(command, flags);
+                return;
             case 'import':
                 await cmdImport(command, flags);
                 return;

package/dist/client.js

@@ -90,7 +90,10 @@ export async function apiCall(method, path, body, cfgOverrideOrOpts) {
     if (method === 'POST' && !headers['Referer']) {
         Object.assign(headers, requestSourceHeaders(cfg));
     }
-    const init = { method, headers };
+    const init = { method, headers,
+        ...(opts.signal ? { signal: opts.signal } : {}),
+        ...(opts.redirect ? { redirect: opts.redirect } : {}),
+    };
     if (body !== undefined && method !== 'GET') {
         init.body = JSON.stringify(body);
     }

package/dist/dev/context.js

@@ -0,0 +1,77 @@
+import { apiCall, hasAuth } from '../client.js';
+import { loadManagedProject } from '../import/project.js';
+function text(value, field) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`开发连接配置缺少 ${field}`);
+    return value;
+}
+function endpoint(value, field) {
+    const url = new URL(text(value, field));
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new Error(`开发连接配置 ${field} 无效`);
+    }
+    return url.href.replace(/\/$/u, '');
+}
+export function parseDevContext(value, appId) {
+    const data = value;
+    if (!data || data.protocolVersion !== 1 || data.appId !== appId || data.env !== 'dev' ||
+        !['SINGLE_ENV', 'MULTI_ENV'].includes(data.mode)) {
+        throw new Error('开发连接协议、应用或环境不匹配，请更新 CLI 或重新导入');
+    }
+    // Whitelist public fields: never persist a server response wholesale.
+    return {
+        protocolVersion: 1,
+        appId,
+        appVersionId: text(data.appVersionId, 'appVersionId'),
+        backendVersionId: text(data.backendVersionId, 'backendVersionId'),
+        env: 'dev',
+        mode: data.mode,
+        domain: endpoint(data.domain, 'domain'),
+        appwrite: {
+            endpoint: endpoint(data.appwrite?.endpoint, 'endpoint'),
+            projectId: text(data.appwrite?.projectId, 'projectId'),
+            databaseId: text(data.appwrite?.databaseId, 'databaseId'),
+            ...(data.appwrite?.storageBucketId ? { storageBucketId: text(data.appwrite.storageBucketId, 'storageBucketId') } : {}),
+        },
+        user: {
+            userId: text(data.user?.userId, 'userId'),
+            userName: typeof data.user?.userName === 'string' ? data.user.userName : '',
+            avatarUrl: typeof data.user?.avatarUrl === 'string' ? data.user.avatarUrl : '',
+        },
+    };
+}
+export async function loadDevContext(root, cfg, environment) {
+    if (!hasAuth(cfg))
+        throw new Error('请先运行 qmuse login');
+    const project = await loadManagedProject(root, cfg, environment);
+    if (!project?.target)
+        throw new Error('请先执行 qmuse import . 并等待云服务 READY，再启动本地联调');
+    const result = await apiCall('POST', '/api/appwrite/local-dev/context', { appId: project.target.appId }, {
+        cfg: { ...cfg, spaceId: project.target.spaceId }, signal: AbortSignal.timeout(30_000), redirect: 'error',
+    });
+    if (!result.ok)
+        throw new Error(`获取开发连接失败：${result.errorMessage || result.errorCode || `HTTP ${result.status}`}`);
+    return parseDevContext(result.data, project.target.appId);
+}
+export function browserRuntime(context) {
+    return {
+        __MUSE__: {
+            appId: context.appId,
+            yfdAppId: context.appId,
+            appVersionId: context.appVersionId,
+            env: context.env,
+            domain: context.domain,
+            appwrite: context.appwrite,
+        },
+        __TERN__: {
+            user: {
+                clientUser: {
+                    ...context.user,
+                    displayName: context.user.userName,
+                    nickName: context.user.userName,
+                },
+                outUserNo: context.user.userId,
+            },
+        },
+    };
+}

package/dist/dev/index.js

@@ -0,0 +1,128 @@
+import { createRequire } from 'node:module';
+import { watchFile, unwatchFile } from 'node:fs';
+import { mkdtemp, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { apiCall } from '../client.js';
+import { loadConfig } from '../config.js';
+import { loadManagedProject } from '../import/project.js';
+import { browserRuntime, loadDevContext } from './context.js';
+import { localDevPlugin } from './plugin.js';
+export async function startDevelopment(options) {
+    const root = await realpath(path.resolve(options.root));
+    const require = createRequire(path.join(root, 'package.json'));
+    let vitePath;
+    try {
+        vitePath = require.resolve('vite');
+    }
+    catch {
+        throw new Error('项目缺少 Vite，请先安装模板依赖');
+    }
+    const project = await loadManagedProject(root, options.cfg, options.environment);
+    if (!project?.target)
+        throw new Error('请先执行 qmuse import . 并等待云服务 READY，再启动本地联调');
+    const serviceFile = await readFile(path.join(root, 'src/services/appwrite.ts'), 'utf8').catch(() => '');
+    if (!serviceFile.includes('__QMUSE_LOCAL_DEV__')) {
+        throw new Error('项目尚未接入本地适配：请按最新版云服务资产在 src/services/appwrite.ts 的 Runtime options 中传入本地 fetch（见 qmuse-cli README）');
+    }
+    const context = await loadDevContext(root, options.cfg, options.environment);
+    const directory = await mkdtemp(path.join(tmpdir(), 'qmuse-local-dev-'));
+    const runtimePath = path.join(directory, 'runtime.json');
+    const previousPath = process.env.MUSE_RUNTIME_CONFIG_PATH;
+    let server;
+    let closed = false;
+    const manifestPath = path.join(root, '.qmuse/project.json');
+    let refresh;
+    let refreshRequested = false;
+    const writeRuntime = async () => {
+        await writeFile(`${runtimePath}.next`, JSON.stringify(browserRuntime(context)), { mode: 0o600 });
+        await rename(`${runtimePath}.next`, runtimePath);
+    };
+    const currentConfig = () => {
+        const cfg = loadConfig(undefined, { environment: options.environment });
+        if (cfg.sessionId !== options.cfg.sessionId || cfg.credentialOrigin !== options.cfg.credentialOrigin || cfg.baseUrl !== options.cfg.baseUrl) {
+            throw new Error('QMuse 登录已变更，请重启 qmuse dev');
+        }
+        return cfg;
+    };
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        unwatchFile(manifestPath);
+        try {
+            await server?.close();
+            await refresh;
+        }
+        finally {
+            await rm(directory, { recursive: true, force: true });
+            if (previousPath === undefined)
+                delete process.env.MUSE_RUNTIME_CONFIG_PATH;
+            else
+                process.env.MUSE_RUNTIME_CONFIG_PATH = previousPath;
+        }
+    };
+    try {
+        await writeRuntime();
+        process.env.MUSE_RUNTIME_CONFIG_PATH = runtimePath;
+        const vite = await import(pathToFileURL(vitePath).href);
+        server = await vite.createServer({
+            root,
+            plugins: [localDevPlugin({
+                    context,
+                    call: async (apiPath, body) => {
+                        const cfg = currentConfig();
+                        const managed = await loadManagedProject(root, cfg, options.environment);
+                        if (managed?.target?.appId !== context.appId)
+                            throw new Error('应用绑定已变更，请重启 qmuse dev');
+                        return apiCall('POST', apiPath, body, {
+                            cfg: { ...cfg, spaceId: managed.target.spaceId },
+                            signal: AbortSignal.timeout(30_000), redirect: 'error',
+                        });
+                    },
+                })],
+            server: {
+                host: '127.0.0.1',
+                port: options.port ?? 5173,
+                strictPort: false,
+                cors: false,
+                open: false,
+                allowedHosts: ['127.0.0.1'],
+            },
+        });
+        if (!server.config.plugins.some(plugin => plugin.name === 'qmuse-sandbox-runtime')) {
+            throw new Error('项目需要支持 runtime config 注入的 @qmuse/vite-config');
+        }
+        await server.listen();
+        watchFile(manifestPath, { interval: 1000 }, (current, previous) => {
+            if (closed || current.mtimeMs === previous.mtimeMs)
+                return;
+            refreshRequested = true;
+            if (refresh)
+                return;
+            refresh = (async () => {
+                do {
+                    refreshRequested = false;
+                    const cfg = currentConfig();
+                    const managed = await loadManagedProject(root, cfg, options.environment);
+                    if (managed?.target?.appId !== context.appId)
+                        throw new Error('应用绑定已变更，请重启 qmuse dev');
+                    const next = await loadDevContext(root, cfg, options.environment);
+                    if (closed)
+                        return;
+                    Object.assign(context, next);
+                    await writeRuntime();
+                    server.ws.send({ type: 'full-reload' });
+                } while (refreshRequested && !closed);
+            })().catch(error => {
+                server.config.logger.error(error instanceof Error ? error.message : '开发配置刷新失败，请重启 qmuse dev');
+            }).finally(() => { refresh = undefined; });
+        });
+        return { server, context, close };
+    }
+    catch (error) {
+        await close();
+        throw error;
+    }
+}

package/dist/dev/plugin.js

@@ -0,0 +1,147 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+const PREFIX = '/__qmuse/local-dev/';
+const TOKEN_HEADER = 'x-qmuse-local-connection';
+const BODY_LIMIT = 64 * 1024;
+const ROUTES = {
+    '/runtime/appwrite/config': 'config',
+    '/runtime/appwrite/auth/custom-token': 'token',
+    '/api/runtime/appwrite/mutation-events': 'mutation-events',
+};
+function respond(res, status, body) {
+    res.writeHead(status, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify(body));
+}
+async function readBody(req) {
+    let length = 0;
+    const chunks = [];
+    for await (const chunk of req) {
+        const bytes = Buffer.from(chunk);
+        length += bytes.length;
+        if (length > BODY_LIMIT)
+            throw new Error('Request too large');
+        chunks.push(bytes);
+    }
+    const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid JSON object');
+    return value;
+}
+export function bridgeSource(context, connection) {
+    const settings = JSON.stringify({ domain: context.domain, routes: ROUTES, prefix: PREFIX, connection, header: TOKEN_HEADER })
+        .replace(/</gu, '\\u003c');
+    return `(() => {
+    const settings = ${settings};
+    const nativeFetch = window.fetch.bind(window);
+    window.__QMUSE_LOCAL_DEV__ = {
+      protocolVersion: 1,
+      async fetch(input, init) {
+        const url = new URL(input instanceof Request ? input.url : String(input), location.href);
+        const base = new URL(settings.domain);
+        const relativePath = url.pathname.slice(base.pathname.replace(/\\/$/, '').length);
+        const route = url.origin === base.origin && url.pathname.startsWith(base.pathname.replace(/\\/$/, '') + '/')
+          ? settings.routes[relativePath] : undefined;
+        if (!route) return nativeFetch(input, init);
+        const request = new Request(input, init);
+        const headers = new Headers(request.headers);
+        headers.set(settings.header, settings.connection);
+        return nativeFetch(settings.prefix + route, {
+          method: request.method, headers,
+          body: request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.text(),
+          credentials: 'same-origin', signal: request.signal, keepalive: request.keepalive
+        });
+      }
+    };
+  })();`;
+}
+export function localDevPlugin(options) {
+    const connection = randomBytes(32).toString('hex');
+    let server;
+    return {
+        name: 'qmuse-local-dev',
+        apply: 'serve',
+        enforce: 'pre',
+        configureServer(vite) {
+            server = vite;
+            server.middlewares.use((req, res, next) => {
+                const address = server.httpServer?.address();
+                const host = address && typeof address !== 'string' ? `127.0.0.1:${address.port}` : '';
+                const origin = `http://${host}`;
+                if (!host || req.headers.host !== host ||
+                    (req.headers.origin && req.headers.origin !== origin) ||
+                    (req.headers['sec-fetch-site'] && !['same-origin', 'none'].includes(String(req.headers['sec-fetch-site'])))) {
+                    respond(res, 403, { success: false, message: 'Invalid local development origin' });
+                    return;
+                }
+                const url = new URL(req.url || '/', origin);
+                if (!url.pathname.startsWith(PREFIX)) {
+                    next();
+                    return;
+                }
+                if (url.pathname === `${PREFIX}bootstrap.js` && req.method === 'GET') {
+                    res.writeHead(200, { 'Content-Type': 'text/javascript', 'Cache-Control': 'no-store', 'Cross-Origin-Resource-Policy': 'same-origin' });
+                    res.end(bridgeSource(options.context, connection));
+                    return;
+                }
+                const provided = req.headers[TOKEN_HEADER];
+                if (req.method !== 'POST' || typeof provided !== 'string' || Buffer.byteLength(provided) !== Buffer.byteLength(connection) ||
+                    !timingSafeEqual(Buffer.from(provided), Buffer.from(connection))) {
+                    respond(res, 403, { success: false, message: 'Invalid local connection' });
+                    return;
+                }
+                void handle(url.pathname.slice(PREFIX.length), req, res).catch(() => {
+                    if (!res.headersSent)
+                        respond(res, 400, { success: false, message: 'Invalid local development request' });
+                });
+            });
+        },
+        transformIndexHtml: {
+            order: 'pre',
+            handler: () => [{ tag: 'script', attrs: { src: `${PREFIX}bootstrap.js` }, injectTo: 'head-prepend' }],
+        },
+    };
+    async function handle(route, req, res) {
+        if (!['config', 'token', 'mutation-events'].includes(route)) {
+            respond(res, 404, { success: false, message: 'Unknown local operation' });
+            return;
+        }
+        const body = await readBody(req);
+        const context = options.context;
+        if (body.appId !== context.appId || (body.env !== undefined && body.env !== 'dev') ||
+            (body.projectId !== undefined && body.projectId !== context.appwrite.projectId)) {
+            respond(res, 409, { success: false, message: 'Application binding changed; restart qmuse dev' });
+            return;
+        }
+        if (route === 'config') {
+            respond(res, 200, { success: true, data: { ...context.appwrite, authTokenEndpoint: '/runtime/appwrite/auth/custom-token' } });
+            return;
+        }
+        const requestBody = { appId: context.appId };
+        if (route === 'mutation-events') {
+            for (const key of ['schemaVersion', 'operation', 'outcome', 'tableId', 'rowId', 'durationMs', 'errorCode']) {
+                if (body[key] !== undefined)
+                    requestBody[key] = body[key];
+            }
+        }
+        const result = await options.call(route === 'token'
+            ? '/runtime/appwrite/auth/custom-token'
+            : '/api/appwrite/local-dev/mutation-events', requestBody);
+        if (!result.ok) {
+            respond(res, result.status >= 400 ? result.status : 502, {
+                success: false, code: result.status, type: result.errorCode,
+                message: result.errorMessage || 'QMuse request failed; check login and restart qmuse dev',
+            });
+            return;
+        }
+        if (route === 'token') {
+            const token = result.data;
+            if (!token || token.projectId !== context.appwrite.projectId || token.endpoint !== context.appwrite.endpoint ||
+                token.databaseId !== context.appwrite.databaseId || typeof token.userId !== 'string' || !token.userId || typeof token.secret !== 'string' || !token.secret) {
+                respond(res, 409, { success: false, message: 'Cloud binding changed; restart qmuse dev' });
+                return;
+            }
+            respond(res, 200, { success: true, data: { userId: token.userId, secret: token.secret, expire: token.expire } });
+            return;
+        }
+        respond(res, 200, { success: true });
+    }
+}

package/dist/import/preflight.js

@@ -4,7 +4,7 @@ import { lstat, readFile, readdir } from 'node:fs/promises';
 import path from 'node:path';
 import ignore from 'ignore';
 const IGNORED_DIRECTORIES = new Set([
-    '.git', '.agents', '.local', '.qmuse', 'node_modules', 'dist', 'build', '.vite', '.turbo',
+    '.git', '.agents', '.local', '.qmuse', '.muse-tmp', 'node_modules', 'dist', 'build', '.vite', '.turbo',
 ]);
 const IGNORED_ROOT_FILES = new Set(['AGENTS.md']);
 const LOCAL_CONTROL_FILES = new Set(['.qmuse-cli.json']);

package/dist/import/update.js

@@ -0,0 +1,25 @@
+import { apiCall } from '../client.js';
+export async function resolveUpdateBase(options) {
+    const { target, cfg, force, interactive, prompt } = options;
+    const response = await apiCall('POST', '/api/appVersion/findAllByAppIdDesc', { appId: target.appId, pageIndex: 1, pageSize: 1 }, { ...cfg, spaceId: target.spaceId });
+    if (!response.ok) {
+        throw new Error(`查询平台最新版本失败：${response.errorMessage ?? response.errorCode ?? `HTTP ${response.status}`}`);
+    }
+    const latest = response.data?.list?.[0];
+    if (!latest || typeof latest.id !== 'string' || !latest.id.trim() || latest.appId !== target.appId) {
+        throw new Error('平台未返回有效的应用最新版本，已停止导入');
+    }
+    const remoteChanged = latest.id !== target.lastVersionId;
+    if (remoteChanged && !force) {
+        const conflict = `平台版本已从 ${target.lastVersionId} 更新为 ${latest.id}`;
+        if (!interactive) {
+            throw new Error(`${conflict}。请同步最新源码；确认以本地源码覆盖时，使用 qmuse import . --force`);
+        }
+        const answer = await prompt(`${conflict}。是否以本地全部源码覆盖平台代码（不会合并平台修改），并在原应用创建新版本？[y/N]：`);
+        if (!/^y(?:es)?$/iu.test(answer.trim())) {
+            throw new Error('已取消覆盖，未上传源码或更改本地版本绑定');
+        }
+    }
+    // Keep the confirmed version fixed so server-side concurrency checks still apply.
+    return { baseVersionId: latest.id, remoteChanged };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qmuse/qmuse-cli",
-  "version": "1.0.2-dev.1",
+  "version": "1.0.3-dev.0",
   "description": "将本地 React 项目安全导入 QMuse 的命令行客户端",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "build": "npm run clean && tsc -p tsconfig.json",
     "qmuse": "tsx src/cli.ts",
     "test": "node --import tsx --test test/*.test.ts",
+    "test:browser": "node --import tsx --test test/dev.browser.ts",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build",
     "publish:public": "bash scripts/publish-public.sh"
@@ -30,10 +31,12 @@
     "node": ">=20"
   },
   "devDependencies": {
+    "@playwright/test": "1.63.0",
     "@types/node": "^22.10.0",
     "@types/yazl": "^3.3.1",
     "tsx": "^4.19.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vite": "7.3.6"
   },
   "license": "MIT",
   "publishConfig": {