@qmuse/qmuse-cli 1.0.0-dev.0

package/README.md

@@ -0,0 +1,145 @@
+# QMuse CLI
+
+`@qmuse/qmuse-cli` 用于登录 QMuse、选择空间，并将本地 React 项目导入 QMuse。首期只公开基础配置、空间、云服务权益预检和导入命令，不提供应用管理、在线对话、代码直改、预览或发布命令。
+
+## 安装
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+本地开发可直接运行：
+
+```bash
+npm run qmuse -- whoami
+```
+
+## 登录
+
+```bash
+qmuse login
+qmuse login --env pre
+qmuse login --status
+qmuse whoami
+```
+
+默认登录会创建一个 120 秒有效的一次性请求，并打开 QMuse `/cli-auth`。用户在网页确认后，CLI 轮询服务端领取并保存 `sessionId`，不启动本地监听端口。
+不带 `--env` 时始终访问线上环境；预发验证的登录及后续命令都需要显式添加 `--env pre`。
+全局参数可以放在命令前或命令后，例如 `qmuse --env pre whoami --json` 与 `qmuse whoami --env pre --json` 等价。
+
+联调时可以使用 `--log` 输出请求接口、网页地址和临时 token。临时 token可以领取登录态，不应发送给其他人。
+
+## 空间
+
+```bash
+qmuse space list
+qmuse space use <spaceId>
+qmuse space info
+```
+
+`space use` 保存当前空间，后续导入会携带对应 `x-space-id`。也可以在导入时通过 `--space-id` 临时指定。
+
+## 导入
+
+```bash
+qmuse import /path/to/react-project --space-id <spaceId>
+```
+
+CLI 会遵循项目根目录的 `.gitignore`，并排除 `.git`、`node_modules`、构建产物、`.env*`、`.qmuse`、`.agents`、`.qmuse-cli.json` 和 `AGENTS.md`。未忽略的私钥、包管理器凭证及常见云凭证会使预检直接失败，不会上传。预检通过后，服务端继续完成项目分析和模板适配、静态资源上传、内容安全审核、云服务处理、构建门禁，以及应用版本创建。
+
+任务只有进入 `READY` 后才会返回并打开 `https://qmuse.cn/app/<appId>`。
+
+导入器不会猜测性改写 React Router、Provider、入口初始化或业务样式。源码、依赖、类型或构建问题会使任务明确失败；CLI 会在源码目录生成 `.qmuse/last-import-error.json`，Codex 或其他大模型可直接读取该文件，修复后重新执行 `qmuse import .`。平台或网络问题不会被误导为源码修改。
+
+### 外部云服务
+
+```bash
+qmuse import ./app --cloud-mode EXTERNAL \
+  --public-config '{"VITE_API_URL":"https://example.test"}'
+```
+
+公开配置只进入受控构建配置，不写入源码。私钥、Service Role Key 等秘密不得通过 `--public-config` 提交。
+
+### QMuse 云服务
+
+```bash
+qmuse cloud init -d "<应用功能描述>"
+qmuse import ./app --cloud-mode QMUSE \
+  --confirm-cloud-service
+```
+
+`cloud init` 只校验当前空间是否具备可用的 QMuse 云服务权益，不创建应用或云资源。首次导入仍会在创建应用后重新校验并开通云服务。安装包同时提供 `qmuse-cli` 兼容命令，因此技能中的既有命令无需修改。
+
+`--confirm-cloud-service` 只确认当前任务的云资源计划，服务端仍会校验用户权限、空间权益和资源额度。
+普通外部仓库迁移到 QMuse 云服务时，使用 `--acknowledge-empty-cloud-data` 明确确认不会自动迁移外部存量数据。
+
+### 恢复任务
+
+```bash
+qmuse import status <jobId> --wait
+qmuse import configure <jobId> --cloud-mode EXTERNAL \
+  --public-config @public-config.json
+```
+
+本地等待中断不会取消服务端任务。对于 QMuse 下载模板，在项目根目录执行 `status --wait`，任务完成后 CLI 会继续更新 `.qmuse/project.json`。
+
+## 首次创建与后续更新
+
+QMuse 下载模板包含 `.qmuse/project.json`：
+
+- 当前环境没有应用绑定时，`qmuse import .` 创建新应用和首个版本。
+- 当前环境已有绑定时，仍执行 `qmuse import .`，在原应用中创建新版本。
+- 源码 hash 未变化时直接返回，不创建任务。
+- 预发、生产和本地环境使用独立绑定。
+
+普通外部仓库没有项目清单，每次导入都创建新应用，CLI 不会修改其本地目录。
+
+项目清单只包含非敏感的平台标识。它不是鉴权凭证，服务端仍会校验空间、应用、版本和源码上传凭证的归属。
+
+## 公开命令
+
+```text
+qmuse help
+qmuse --version
+qmuse whoami
+qmuse login
+qmuse logout
+qmuse config
+qmuse space list
+qmuse space use <spaceId>
+qmuse space info
+qmuse cloud init
+qmuse import
+qmuse import status
+qmuse import configure
+```
+
+## 开发验证
+
+```bash
+npm run build
+npm test
+```
+
+## 公网发布
+
+先在 `package.json` 中设置未发布的语义化版本，然后执行：
+
+```bash
+npm run publish:public
+```
+
+发布脚本默认使用 `dev` tag，也可以选择 `latest`。仓库中的内部包名不会被修改；脚本仅在发布期间将 npm 包名动态替换为 `@qmuse/qmuse-cli`，结束或失败后自动恢复。发布前可执行 `npm run publish:public -- --dry-run` 验证最终公网包。
+
+主要模块：
+
+- `src/cli.ts`：命令解析和公开命令路由
+- `src/login.ts`：浏览器确认登录
+- `src/cloud.ts`：QMuse 云服务权益预检
+- `src/import/preflight.ts`：本地只读预检和源码 hash
+- `src/import/project.ts`：受管项目清单校验与原子更新
+- `src/import/archive.ts`：确定性源码 ZIP
+- `src/import/api.ts`：Import Job API
+- `src/import/poll.ts`：任务状态轮询

package/dist/api.js

@@ -0,0 +1,20 @@
+import { apiCall } from './client.js';
+/** 校验并续期已有 sessionId。 */
+export function exchangeSessionCookie(sessionId, opts) {
+    return apiCall('POST', '/api/login/session-cookie', { sessionId }, { anonymous: true, ...opts });
+}
+/** 创建待网页确认的 CLI 登录请求。 */
+export function createSessionExchangeRequest(opts) {
+    return apiCall('POST', '/api/login/session-exchange/request', {}, { anonymous: true, ...opts });
+}
+/** 使用一次性 token 换取 CLI sessionId。 */
+export function consumeSessionExchangeToken(token, opts) {
+    return apiCall('POST', '/api/login/session-exchange/consume', { token }, { anonymous: true, ...opts });
+}
+export function listSpaces(pageIndex = 1, pageSize = 20, cfg) {
+    const path = `/api/space/list?pageIndex=${pageIndex}&pageSize=${pageSize}`;
+    return apiCall('GET', path, undefined, cfg);
+}
+export function spaceInfo(cfg) {
+    return apiCall('GET', '/api/space/info', undefined, cfg);
+}