npm - @lark-apaas/miaoda-cli - Versions diffs - 0.1.31 → 0.1.33-alpha.59a1bf2 - Mend

@lark-apaas/miaoda-cli 0.1.31 → 0.1.33-alpha.59a1bf2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md +2 -2
package/dist/cli/commands/registry/index.js +6 -6
package/dist/cli/handlers/app/migrate.js +122 -58
package/dist/cli/handlers/registry/add.js +3 -2
package/dist/cli/handlers/registry/list.js +3 -8
package/dist/cli/handlers/registry/shared.js +8 -4
package/dist/utils/index.js +5 -1
package/dist/utils/preview-control.js +107 -0
package/dist/utils/sandbox-skills.js +13 -1
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -55,7 +55,7 @@ miaoda file ls --output json
 `miaoda registry` 提供 shadcn 式的「组件 registry」：把 SDK 文件**拷进**当前项目（copy-in），而非作为依赖安装。registry 是独立 npm 包，按运行时分发（design-html / html → buildless runtime → `@lark-apaas/coding-registry-buildless`）。
-前置：当前目录（或 `--dir`）已走过 `miaoda app init`，且 `.spark/meta.json` 的 `stack` 有对应 registry 包（当前支持 `design-html` / `html`）；其余 stack 执行时报 `REGISTRY_STACK_UNSUPPORTED` 并提示支持列表。
+前置：当前工作目录已走过 `miaoda app init`，且 `.spark/meta.json` 的 `stack` 有对应 registry 包（当前支持 `design-html` / `html`）；其余 stack 执行时报 `REGISTRY_STACK_UNSUPPORTED` 并提示支持列表。meta 一律从 cwd 读取，不随 `--dir` 走。
 ```bash
 # 列出可用 SDK 条目（输出各文件 USAGE 注释块原文，便于 Agent 直接读用法）
@@ -76,7 +76,7 @@ miaoda registry add deck-slide --overwrite         # 目标已存在时覆盖（
 - **拍平落地**：所有文件**拍平**到项目根（`scripts/deck-slide.js` → 项目 `deck-slide.js`，不保留子目录）；闭包内同名 basename 撞车时后者覆盖前者。
 - **skip-by-disk**：项目已有同名（拍平后的 basename）文件默认跳过，`--overwrite` 才覆盖；不写任何安装记账文件，项目文件树即状态。
 - **add 回执带 usage**：`add` 结果的 `entries` 只列**你请求的条目**（不含被 `Depends` 传递拉进来的依赖——依赖照常落地在 `added`/`skipped`，但那是"管道"），逐条给出 `usage`（USAGE 块原文）与 `dependsOn`，Agent `add` 完即可直接读用法，无需再 `registry list`。请求的条目即使已存在被跳过也回带 usage（`status` 标 `added`/`skipped`，据此判断磁盘上是 registry 版还是你改过的旧版）。`--json` 结构为 `{registryVersion, added, skipped, dryRun, entries}`；pretty（默认）输出 `registry@<ver>` + `added:`/`skipped:` 逗号列表 + 各请求条目的 USAGE 块，稳定 label、无 JSON 数组、无截断，对 Agent 与人同样可读。
-- `--version <ver>` 指定 registry 包版本或 dist-tag（缺省 `latest`），`--dir <path>` 指定项目目录（缺省当前目录）。
+- `--version <ver>` 指定 registry 包版本或 dist-tag（缺省 `latest`）；`add` 的 `--dir <path>` 指定 copy-in 落地目录（缺省当前目录），不影响 `.spark/meta.json` 读取。
 ## 全局参数

package/dist/cli/commands/registry/index.js CHANGED Viewed

@@ -33,8 +33,9 @@ function registerRegistryCommands(program) {
   - add 落地：拍平到项目根（包根 scripts/x.js → 项目 x.js）；同名 basename 撞车时后者覆盖前者
 前置
-  当前目录（或 --dir）已走过 'miaoda app init'，且 .spark/meta.json 的 stack 有对应
+  当前工作目录已走过 'miaoda app init'，且 .spark/meta.json 的 stack 有对应
   registry 包（当前支持 design-html / html）；其余 stack 执行时报 REGISTRY_STACK_UNSUPPORTED
+  meta 一律从 cwd 读取，add 的 --dir 只影响 copy-in 落地目录
 `);
     registerRegistryList(registryCmd);
     registerRegistryAdd(registryCmd);
@@ -43,7 +44,6 @@ function registerRegistryList(parent) {
     const cmd = parent
         .command('list')
         .description('列出 registry 可用 SDK 条目，输出各文件的 USAGE 块原文')
-        .option('--dir <path>', '项目目录，默认当前目录', '.')
         .option('--version <ver>', 'registry 包版本或 dist-tag，缺省 latest')
         .addHelpText('after', `
 输出
@@ -59,7 +59,6 @@ JSON 输出
 `);
     cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
         await (0, index_1.handleRegistryList)({
-            dir: rawOpts.dir,
             version: rawOpts.version,
         });
     }));
@@ -69,7 +68,7 @@ function registerRegistryAdd(parent) {
         .command('add')
         .description('把一个或多个 SDK 文件 copy-in 到当前项目（拍平到项目根，含 Depends 闭包）')
         .argument('<token...>', 'name / 完整文件名 / relPath，可传多个；同名多匹配全拉，Depends 自动传递解析')
-        .option('--dir <path>', '项目目录，默认当前目录', '.')
+        .option('--dir <path>', 'copy-in 落地目录，默认当前目录（stack 一律读 cwd 的 .spark/meta.json）', '.')
         .option('--version <ver>', 'registry 包版本或 dist-tag，缺省 latest')
         .option('--overwrite', '目标文件已存在时覆盖（默认跳过以保护用户改动）', false)
         .option('--dry-run', '只报告将写 / 将跳哪些文件，不落盘', false)
@@ -77,8 +76,9 @@ function registerRegistryAdd(parent) {
 行为
   - token 寻址：name（foo）/ 完整文件名（foo.css）/ relPath（stylesheets/foo.css）任一形式
   - 多匹配全拉：token 命中多个同名条目时全部 copy-in；想只要其一就写完整文件名 / relPath
-  - 解析 USAGE 块 Depends 传递闭包，把 SDK 文件**拍平**拷到项目根
-    （包根 scripts/deck-stage.js → 项目 deck-stage.js；同名 basename 撞车时后者覆盖前者）
+  - 解析 USAGE 块 Depends 传递闭包，把 SDK 文件**拍平**拷到落地目录（--dir，默认当前目录）
+    （包根 scripts/deck-stage.js → 落地 deck-stage.js；同名 basename 撞车时后者覆盖前者）
+  - stack 一律读当前工作目录的 .spark/meta.json，--dir 不影响 meta 读取
   - skip-by-disk：目标文件已存在默认跳过；--overwrite 才覆盖
   - 不写任何安装记账文件（项目文件树即状态）

package/dist/cli/handlers/app/migrate.js CHANGED Viewed

@@ -15,6 +15,7 @@ const spark_meta_1 = require("../../../utils/spark-meta");
 const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const env_1 = require("../../../utils/env");
+const preview_control_1 = require("../../../utils/preview-control");
 const logger_1 = require("../../../utils/logger");
 /**
  * miaoda app migrate --to <stack> [--from <stack>] [--dir <path>]
@@ -99,78 +100,130 @@ async function handleAppMigrate(opts) {
     // 的 miaodaTemplate.archType 拿到的动态值，rule 配置时不知道，由 handler 在拿到
     // renderTemplate 结果后单独写。version 也一并写回方便 sync 后续诊断。
     (0, spark_meta_1.writeSparkMeta)(targetDir, { archType: templateArchType, version: templateVersion });
-    // 清掉 user app 的 node_modules —— migrate 改了 dependencies 集合（删 lite + 加 NestJS
-    // 全套）+ rule 已经把 package-lock.json 删了。如果 node_modules 留着，npm install 时旧
-    // 包还在 node_modules 顶层 hoist 树里，可能跟新 package.json spec 撞 peer 冲突
-    // （比如旧 coding-preset-vite-react@1.0.8 peer vite@^8 跟新 vite@^7 撞）。
-    // 软失败：node_modules 不存在不报错。
-    const nodeModulesPath = node_path_1.default.join(targetDir, 'node_modules');
-    if (node_fs_1.default.existsSync(nodeModulesPath)) {
-        (0, logger_1.log)('migrate', '清理 node_modules（dependencies 集合已变）...');
-        node_fs_1.default.rmSync(nodeModulesPath, { recursive: true, force: true });
+    // 沙箱环境下先停掉 dev server（预览）—— 保活由 code-server 管，`pkill dev.js` 会被立刻
+    // 重新拉起，拿不到"停住"的状态。dev server 活着时 vite 持续往 node_modules/.vite/deps 写
+    // 文件，下面 rm node_modules 走到顶层 rmdir 时目录又非空，直接 ENOTEMPTY 失败（历史故障）。
+    //   - 只在沙箱内做（本地用户自己管 dev 进程，不该被 CLI 动）
+    //   - 软失败：接口不存在（老版本 code-server 返 404）/ 连不上都不阻断，降级回老路径
+    //     （带重试的 rm + 结尾 pkill 让保活拉起）
+    //   - ⚠️ stop 成功后必须恢复：下面整段包在 try/finally 里，任何异常路径都会走 startPreview
+    let previewStopped = false;
+    let previewStopError;
+    if ((0, env_1.isSandboxEnv)()) {
+        (0, logger_1.log)('migrate', '停止 dev server(预览)以便安全重装依赖...');
+        const stopped = await (0, preview_control_1.stopPreview)({ logPrefix: 'migrate' });
+        previewStopped = stopped.ok;
+        if (!stopped.ok) {
+            previewStopError = stopped.error;
+            (0, logger_1.log)('migrate', `⚠ 停止预览失败 (continuing, 降级为不停 dev 直接重装): ${stopped.error ?? ''}`);
+        }
     }
-    // 跑 npm install 物化新依赖集合 + 把 followLatestPackages 钉 latest
-    // --ignore-scripts 绕开 action-plugin postinstall 在缺平台 env 时的 ENOENT
-    // --registry 钉同一份 npmmirror（跟 init / sync 行为一致）
-    // 软失败：install 挂了不阻断 emit；用户拿到详细 error，自行 npm install 兜底
     const followLatest = config.followLatestPackages ?? [];
-    const installArgs = [
-        'install',
-        '--no-audit',
-        '--no-fund',
-        '--ignore-scripts',
-        '--registry',
-        (0, index_2.resolveNpmInstallRegistry)(),
-        ...followLatest.map((pkg) => `${pkg}@latest`),
-    ];
-    (0, logger_1.log)('migrate', `Running npm ${installArgs.join(' ')}...`);
     let installError;
+    let nodeModulesCleanError;
+    let previewRestarted = false;
+    let previewRestartError;
     try {
-        (0, node_child_process_1.execFileSync)('npm', installArgs, {
-            cwd: targetDir,
-            stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
-        });
-    }
-    catch (err) {
-        installError = err instanceof Error ? err.message : String(err);
-        (0, logger_1.log)('migrate', `⚠ npm install failed (continuing): ${installError}`);
-    }
-    // 重启 dev process 前清 vite cache —— migrate 改了 package.json + lockfile,
-    // 老 vite 进程的 .vite/deps cache 的 lockfileHash 跟新 lockfile 不一致。
-    // 不清的话 supervisor 拉起的新 vite cold start 会立即 "Re-optimizing because
-    // lockfile has changed", re-optimize 期间 ModuleGraph transform cache 跟
-    // deps middleware metadata 短暂不同步, 浏览器请求老 hash 触发
-    // ERR_OUTDATED_OPTIMIZED_DEP → 504 死锁(详见 fullstack-plugin#1143 的 504
-    // ignoreOutdatedRequests fix 注释)。直接 rm -rf 让新 vite 从干净状态 cold
-    // optimize, 一次写到位 lockfile 一致的 metadata, 不再触发中途 re-optimize。
-    //
-    //   - 只在 SANDBOX_ID 非空时做(本地一般不会撞这条链路)
-    //   - 只在 install 成功时做(install 挂了 node_modules 状态不对, 清 cache 也救不回来)
-    //   - 软失败:.vite 不存在 / 删失败都不阻断
-    if (installError === undefined &&
-        process.env.SANDBOX_ID !== undefined &&
-        process.env.SANDBOX_ID !== '') {
-        const viteCacheDir = node_path_1.default.join(targetDir, 'node_modules', '.vite');
-        if (node_fs_1.default.existsSync(viteCacheDir)) {
-            (0, logger_1.log)('migrate', '清理 node_modules/.vite (vite cache 跟新 lockfile 错位会 504)...');
+        // 清掉 user app 的 node_modules —— migrate 改了 dependencies 集合（删 lite + 加 NestJS
+        // 全套）+ rule 已经把 package-lock.json 删了。如果 node_modules 留着，npm install 时旧
+        // 包还在 node_modules 顶层 hoist 树里，可能跟新 package.json spec 撞 peer 冲突
+        // （比如旧 coding-preset-vite-react@1.0.8 peer vite@^8 跟新 vite@^7 撞）。
+        //   - maxRetries：force 只吞 ENOENT，不管 ENOTEMPTY/EBUSY；这类错误 node 只在
+        //     maxRetries>0 时才重试。停预览失败降级时靠它兜住残余写入。
+        //   - 软失败：删不干净也继续跑 npm install 让 npm 自己 reconcile —— 半迁移态
+        //     （package-lock 已删 + 新 deps 没装）比"清理不彻底"糟得多。
+        const nodeModulesPath = node_path_1.default.join(targetDir, 'node_modules');
+        if (node_fs_1.default.existsSync(nodeModulesPath)) {
+            (0, logger_1.log)('migrate', '清理 node_modules（dependencies 集合已变）...');
             try {
-                node_fs_1.default.rmSync(viteCacheDir, { recursive: true, force: true });
+                node_fs_1.default.rmSync(nodeModulesPath, {
+                    recursive: true,
+                    force: true,
+                    maxRetries: 5,
+                    retryDelay: 300,
+                });
             }
             catch (err) {
-                (0, logger_1.log)('migrate', `⚠ 清 .vite 失败 (continuing): ${err instanceof Error ? err.message : String(err)}`);
+                nodeModulesCleanError = err instanceof Error ? err.message : String(err);
+                (0, logger_1.log)('migrate', `⚠ 清理 node_modules 失败 (continuing): ${nodeModulesCleanError}`);
+            }
+        }
+        // 跑 npm install 物化新依赖集合 + 把 followLatestPackages 钉 latest
+        // --ignore-scripts 绕开 action-plugin postinstall 在缺平台 env 时的 ENOENT
+        // --registry 钉同一份 npmmirror（跟 init / sync 行为一致）
+        // 软失败：install 挂了不阻断 emit；用户拿到详细 error，自行 npm install 兜底
+        const installArgs = [
+            'install',
+            '--no-audit',
+            '--no-fund',
+            '--ignore-scripts',
+            '--registry',
+            (0, index_2.resolveNpmInstallRegistry)(),
+            ...followLatest.map((pkg) => `${pkg}@latest`),
+        ];
+        (0, logger_1.log)('migrate', `Running npm ${installArgs.join(' ')}...`);
+        try {
+            (0, node_child_process_1.execFileSync)('npm', installArgs, {
+                cwd: targetDir,
+                stdio: (0, output_1.isJsonMode)() ? ['ignore', 'ignore', 'inherit'] : 'inherit',
+            });
+        }
+        catch (err) {
+            installError = err instanceof Error ? err.message : String(err);
+            (0, logger_1.log)('migrate', `⚠ npm install failed (continuing): ${installError}`);
+        }
+        // 重启 dev process 前清 vite cache —— migrate 改了 package.json + lockfile,
+        // 老 vite 进程的 .vite/deps cache 的 lockfileHash 跟新 lockfile 不一致。
+        // 不清的话拉起的新 vite cold start 会立即 "Re-optimizing because
+        // lockfile has changed", re-optimize 期间 ModuleGraph transform cache 跟
+        // deps middleware metadata 短暂不同步, 浏览器请求老 hash 触发
+        // ERR_OUTDATED_OPTIMIZED_DEP → 504 死锁(详见 fullstack-plugin#1143 的 504
+        // ignoreOutdatedRequests fix 注释)。直接 rm -rf 让新 vite 从干净状态 cold
+        // optimize, 一次写到位 lockfile 一致的 metadata, 不再触发中途 re-optimize。
+        //
+        //   - 只在 SANDBOX_ID 非空时做(本地一般不会撞这条链路)
+        //   - 只在 install 成功时做(install 挂了 node_modules 状态不对, 清 cache 也救不回来)
+        //   - 软失败:.vite 不存在 / 删失败都不阻断
+        if (installError === undefined &&
+            process.env.SANDBOX_ID !== undefined &&
+            process.env.SANDBOX_ID !== '') {
+            const viteCacheDir = node_path_1.default.join(targetDir, 'node_modules', '.vite');
+            if (node_fs_1.default.existsSync(viteCacheDir)) {
+                (0, logger_1.log)('migrate', '清理 node_modules/.vite (vite cache 跟新 lockfile 错位会 504)...');
+                try {
+                    node_fs_1.default.rmSync(viteCacheDir, { recursive: true, force: true });
+                }
+                catch (err) {
+                    (0, logger_1.log)('migrate', `⚠ 清 .vite 失败 (continuing): ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+    }
+    finally {
+        // 恢复 dev server —— 只要上面 stop 成功过就必须调，且必须在 finally 里：
+        // rule 应用 / install / 清 cache 任何一步抛异常都不能把保活留在关闭状态，否则用户沙箱
+        // 的预览再也起不来（比迁移失败严重得多）。
+        // 无条件恢复（不看 installError）：dev 进程已经被停了，留着不起来只会更糟；新 scripts/dev.js
+        // + 新依赖也正是靠这次 start 生效。
+        if (previewStopped) {
+            (0, logger_1.log)('migrate', '恢复 dev server(预览)...');
+            const started = await (0, preview_control_1.startPreview)({ logPrefix: 'migrate' });
+            previewRestarted = started.ok;
+            if (!started.ok) {
+                previewRestartError = started.error;
+                (0, logger_1.log)('migrate', `✗ 恢复预览失败, 需人工处理: ${started.error ?? ''}`);
             }
         }
     }
-    // 沙箱环境下重启 dev process —— scripts/dev.js 被 fullstack 版本覆盖了,但当前正在
-    // 跑的 node 进程仍按老逻辑工作(只起 vite,没起 nest),整体没切到 fullstack 模式。
-    // 通过 pkill 杀掉 dev.js 主进程,依赖沙箱平台 supervisor 自动重新 exec dev.sh → dev.js,
-    // 新进程用新 deps + 新 scripts,正常进入 fullstack 模式。
+    // 降级路径：preview stop 没成功（老版本 code-server / 接口连不上），dev 进程还是老的，
+    // 按历史行为 pkill 掉 dev.js 主进程，靠平台 supervisor 自动重新 exec dev.sh → dev.js，
+    // 让新 deps + 新 scripts 生效。
     //   - 只在沙箱内做(isSandboxEnv;本地环境用户进程混杂,主动 pkill 风险大)
     //   - install 挂了不做 —— 新依赖不全, 杀旧 dev 后新 dev 起不来反而更糟,
     //     留着旧进程让用户先处理 installError
     //   - 软失败:pkill 无匹配进程退出 1,catch 吞掉
-    let devRestarted = false;
-    if (installError === undefined && (0, env_1.isSandboxEnv)()) {
+    let devRestarted = previewRestarted;
+    if (!previewStopped && installError === undefined && (0, env_1.isSandboxEnv)()) {
         (0, logger_1.log)('migrate', '沙箱环境,重启 dev process(平台 supervisor 会自动拉起)...');
         try {
             (0, node_child_process_1.execFileSync)('pkill', ['-f', 'node.*scripts/dev\\.js'], { stdio: 'ignore' });
@@ -194,11 +247,22 @@ async function handleAppMigrate(opts) {
             ...summarizeResults(results),
             followLatestPackages: followLatest,
             installError,
+            nodeModulesCleanError,
             devRestarted,
+            previewStopped,
+            previewStopError,
+            previewRestarted,
+            previewRestartError,
             nextActions: (0, env_1.isSandboxEnv)()
                 ? [
                     'git status / git diff 评估改动并 commit',
                     'miaoda skills sync 同步到新 stack 的 agent skills',
+                    // 预览恢复失败时置顶一条人工兜底动作 —— 保活已被关掉且不会自愈
+                    ...(previewRestartError === undefined
+                        ? []
+                        : [
+                            `⚠ dev server(预览)未恢复成功，需手动 curl -X POST ${(0, preview_control_1.resolveCodeServerBaseUrl)()}/api/v1/preview/start 恢复保活`,
+                        ]),
                 ]
                 : [
                     'git status / git diff 评估改动并 commit',

package/dist/cli/handlers/registry/add.js CHANGED Viewed

@@ -13,7 +13,8 @@ const output_1 = require("../../../utils/output");
  * miaoda registry add <name...> [--overwrite] [--dry-run] [--dir <path>] [--version <ver>]
  *
  * 解析 USAGE 块 Depends 传递闭包，把每个条目对应的 SDK 文件从 registry 包根的 <relPath>
- * **保留相对路径**拷到项目根（--dir 指定目录的根）。
+ * **保留相对路径**拷到落地目录（--dir，默认 cwd）。stack 一律从 <cwd>/.spark/meta.json 读，
+ * 不随 --dir 走。
  * skip-by-disk：目标已存在默认跳过，--overwrite 才覆盖。不写任何安装记账文件。
  */
 async function handleRegistryAdd(opts) {
@@ -22,7 +23,7 @@ async function handleRegistryAdd(opts) {
         throw new error_1.AppError('ARGS_INVALID', 'registry add 至少需要一个条目名');
     }
     const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
-    const stack = (0, shared_1.resolveRegistryStack)(targetDir);
+    const stack = (0, shared_1.resolveRegistryStack)();
     const reg = (0, index_1.loadRegistry)({ stack, version: opts.version });
     try {
         const plan = (0, index_1.planAdd)({

package/dist/cli/handlers/registry/list.js CHANGED Viewed

@@ -1,17 +1,13 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleRegistryList = handleRegistryList;
-const node_path_1 = __importDefault(require("node:path"));
 const index_1 = require("../../../services/registry/index");
 const shared_1 = require("./shared");
 const output_1 = require("../../../utils/output");
 /**
- * miaoda registry list [--dir <path>] [--version <ver>]
+ * miaoda registry list [--version <ver>]
  *
- * 从 .spark/meta.json 读 stack → runtime → 包名，拉对应 registry 包，从包根递归扫含 USAGE 块的 SDK 文件。
+ * 从 <cwd>/.spark/meta.json 读 stack → runtime → 包名，拉对应 registry 包，从包根递归扫含 USAGE 块的 SDK 文件。
  *
  * - 默认（pretty）：输出各条目 USAGE 块原文，带文件名分隔，给 Agent 直接读注释。
  * - --json：输出 [{name, file, usage(原文字符串), dependsOn[]}]，usage 保持原文不解析成字段。
@@ -19,8 +15,7 @@ const output_1 = require("../../../utils/output");
  */
 async function handleRegistryList(opts) {
     await Promise.resolve();
-    const targetDir = node_path_1.default.resolve(opts.dir ?? process.cwd());
-    const stack = (0, shared_1.resolveRegistryStack)(targetDir);
+    const stack = (0, shared_1.resolveRegistryStack)();
     const reg = (0, index_1.loadRegistry)({ stack, version: opts.version });
     try {
         if ((0, output_1.isJsonMode)()) {

package/dist/cli/handlers/registry/shared.js CHANGED Viewed

@@ -5,16 +5,20 @@ const spark_meta_1 = require("../../../utils/spark-meta");
 const index_1 = require("../../../services/registry/index");
 const error_1 = require("../../../utils/error");
 /**
- * 从 <targetDir>/.spark/meta.json 读 stack，校验该 stack 有组件 registry。
+ * 从 <cwd>/.spark/meta.json 读 stack，校验该 stack 有组件 registry。
+ * meta 只与当前工作目录相关（CLI 必须在 user app 根目录下运行），不随 --dir 走——
+ * --dir 只影响 add 的 copy-in 落地目录。
  * 缺 stack → 提示先 init；stack 无 registry（无对应 runtime / runtime 无 registry 包）→ 提示支持哪些 stack。
  *
  * 这里只做「stack 是否在支持列表」的早校验给用户友好提示；包名的两跳解析
  * （stack → runtime → 包）由 loadRegistry/resolveRegistryPackage 负责。
  */
-function resolveRegistryStack(targetDir) {
-    const meta = (0, spark_meta_1.readSparkMeta)(targetDir);
+function resolveRegistryStack() {
+    const meta = (0, spark_meta_1.readSparkMeta)(process.cwd());
     if (meta.stack === undefined || meta.stack === '') {
-        throw new error_1.AppError('REGISTRY_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first');
+        throw new error_1.AppError('REGISTRY_META_INCOMPLETE', '.spark/meta.json missing stack — run `miaoda app init` first', {
+            next_actions: ['meta 一律读当前工作目录（不随 --dir），请 cd 到 user app 根目录后重试'],
+        });
     }
     if (!index_1.REGISTRY_SUPPORTED_STACKS.includes(meta.stack)) {
         throw new error_1.AppError('REGISTRY_STACK_UNSUPPORTED', `stack "${meta.stack}" 没有组件 registry`, {

package/dist/utils/index.js CHANGED Viewed

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pollUntilDone = exports.msToSec = exports.msToNs = exports.parseToSec = exports.parseToNs = exports.parseToMs = exports.parseTimeToMs = exports.isSandboxEnv = exports.getInnerApi = exports.postInnerApi = exports.setRuntimeHttpClient = exports.setHttpClient = exports.resetHttpClient = exports.getRuntimeHttpClient = exports.getHttpClient = exports.log = exports.debug = exports.fmt = exports.isJsonMode = exports.emitPaged = exports.emitOk = exports.emitError = exports.emit = exports.getLogId = exports.generateLogId = exports.initConfigFromOpts = exports.resetConfig = exports.setConfig = exports.getConfig = exports.HttpError = exports.AppError = void 0;
+exports.pollUntilDone = exports.msToSec = exports.msToNs = exports.parseToSec = exports.parseToNs = exports.parseToMs = exports.parseTimeToMs = exports.resolveCodeServerBaseUrl = exports.startPreview = exports.stopPreview = exports.isSandboxEnv = exports.getInnerApi = exports.postInnerApi = exports.setRuntimeHttpClient = exports.setHttpClient = exports.resetHttpClient = exports.getRuntimeHttpClient = exports.getHttpClient = exports.log = exports.debug = exports.fmt = exports.isJsonMode = exports.emitPaged = exports.emitOk = exports.emitError = exports.emit = exports.getLogId = exports.generateLogId = exports.initConfigFromOpts = exports.resetConfig = exports.setConfig = exports.getConfig = exports.HttpError = exports.AppError = void 0;
 var error_1 = require("./error");
 Object.defineProperty(exports, "AppError", { enumerable: true, get: function () { return error_1.AppError; } });
 Object.defineProperty(exports, "HttpError", { enumerable: true, get: function () { return error_1.HttpError; } });
@@ -32,6 +32,10 @@ Object.defineProperty(exports, "postInnerApi", { enumerable: true, get: function
 Object.defineProperty(exports, "getInnerApi", { enumerable: true, get: function () { return http_1.getInnerApi; } });
 var env_1 = require("./env");
 Object.defineProperty(exports, "isSandboxEnv", { enumerable: true, get: function () { return env_1.isSandboxEnv; } });
+var preview_control_1 = require("./preview-control");
+Object.defineProperty(exports, "stopPreview", { enumerable: true, get: function () { return preview_control_1.stopPreview; } });
+Object.defineProperty(exports, "startPreview", { enumerable: true, get: function () { return preview_control_1.startPreview; } });
+Object.defineProperty(exports, "resolveCodeServerBaseUrl", { enumerable: true, get: function () { return preview_control_1.resolveCodeServerBaseUrl; } });
 var time_1 = require("./time");
 Object.defineProperty(exports, "parseTimeToMs", { enumerable: true, get: function () { return time_1.parseTimeToMs; } });
 Object.defineProperty(exports, "parseToMs", { enumerable: true, get: function () { return time_1.parseToMs; } });

package/dist/utils/preview-control.js ADDED Viewed

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCodeServerBaseUrl = resolveCodeServerBaseUrl;
+exports.stopPreview = stopPreview;
+exports.startPreview = startPreview;
+const logger_1 = require("../utils/logger");
+/**
+ * 沙箱内 dev server（预览）的显式启停控制。
+ *
+ * 沙箱里 dev server 的保活由 code-server 负责：直接 `pkill dev.js` 只会被保活立刻重新拉起，
+ * 拿不到"停住"这个状态。code-server 为此暴露了两个本地接口：
+ *
+ *   POST <base>/api/v1/preview/stop    停止预览（连带停掉保活）
+ *   POST <base>/api/v1/preview/start   启动预览（恢复保活）
+ *
+ * base 默认 `http://localhost:8080/code-server` —— migrate / sync 这类脚本本身就在沙箱内执行，
+ * 直连 localhost 即可，无需鉴权；`MIAODA_CODE_SERVER_BASE_URL` 可覆盖（本地联调 / 端口变更）。
+ *
+ * 典型用途：migrate 要重装依赖（`rm -rf node_modules` + `npm install`）。dev server 活着时
+ * vite 会持续往 `node_modules/.vite/deps` 写文件，`fs.rmSync` 自底向上删到顶层 `rmdir` 时目录
+ * 又变非空，直接 `ENOTEMPTY` 失败。先 stop 再删才是干净的做法。
+ *
+ * ⚠️ 调用契约：**stop 成功后必须保证 start 被调到**（调用方放 `finally`）。保活被关掉后不会
+ * 自愈，漏掉 start 会让用户沙箱的预览再也起不来 —— 比迁移失败严重得多。
+ *
+ * 全部 API 都是软失败语义：不抛异常，失败信息放在返回值的 `error` 上，由调用方决定降级路径
+ * （老版本 code-server 没有这两个接口，会返回 404）。
+ */
+const DEFAULT_CODE_SERVER_BASE_URL = 'http://localhost:8080/code-server';
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** start 是恢复动作，值得多试几次；stop 失败可以直接降级，不重试 */
+const START_ATTEMPTS = 3;
+const START_RETRY_DELAY_MS = 500;
+/** code-server 本地基址，去掉尾部斜杠。`MIAODA_CODE_SERVER_BASE_URL` > 默认 localhost:8080。 */
+function resolveCodeServerBaseUrl() {
+    const fromEnv = process.env.MIAODA_CODE_SERVER_BASE_URL;
+    const base = fromEnv !== undefined && fromEnv !== '' ? fromEnv : DEFAULT_CODE_SERVER_BASE_URL;
+    return base.replace(/\/+$/, '');
+}
+/** 停止预览（含保活）。软失败：不抛异常。 */
+async function stopPreview(opts = {}) {
+    return postPreview('stop', 1, opts);
+}
+/** 启动预览（恢复保活）。软失败：不抛异常；内部带重试，因为这是恢复动作。 */
+async function startPreview(opts = {}) {
+    return postPreview('start', START_ATTEMPTS, opts);
+}
+async function postPreview(action, attempts, opts) {
+    const url = `${resolveCodeServerBaseUrl()}/api/v1/preview/${action}`;
+    const logPrefix = opts.logPrefix ?? 'preview';
+    let last = { ok: false, url, error: 'no attempt made' };
+    for (let i = 1; i <= attempts; i++) {
+        last = await postOnce(url, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        if (last.ok)
+            return last;
+        if (i < attempts) {
+            (0, logger_1.log)(logPrefix, `⚠ preview ${action} 失败(第 ${String(i)}/${String(attempts)} 次), 重试: ${last.error ?? ''}`);
+            await sleep(START_RETRY_DELAY_MS);
+        }
+    }
+    return last;
+}
+async function postOnce(url, timeoutMs) {
+    try {
+        // 带空 JSON body —— 这两个接口不需要参数，但显式给 content-type 可以避免服务端框架对
+        // 无 body POST 的处理差异。
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: '{}',
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok) {
+            const detail = await readBodySafe(res);
+            return {
+                ok: false,
+                url,
+                status: res.status,
+                error: `POST ${url} → ${String(res.status)} ${res.statusText}${detail}`,
+            };
+        }
+        return { ok: true, url, status: res.status };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            url,
+            error: `POST ${url} failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+async function readBodySafe(res) {
+    try {
+        const text = await res.text();
+        if (!text)
+            return '';
+        return ` ${text.length > 300 ? `${text.slice(0, 300)}...` : text}`;
+    }
+    catch {
+        return '';
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/utils/sandbox-skills.js CHANGED Viewed

@@ -128,7 +128,16 @@ function syncSandboxSkills(opts) {
         (0, logger_1.debug)(`sandbox-skills: no npm version matched -alpha.${lane}, fallback to @latest ` +
             `(TCC 里的 X 可能是老 lane dist-tag 命名 / 已 unpublish / npm view 挂 / 网络断)`);
     }
-    const primaryVersion = laneVersion ?? 'latest';
+    // 版本优先级：lane（TCC 显式定向）> BOE 默认 @dev > @latest
+    //
+    // `dev` 通道由 miaoda-coding 的 publish-sandbox-skills-dev.sh 在 develop 分支自动发布
+    // （`<base>-dev.<sha>` + dist-tag `dev`），口径与 coding-steering 完全一致 ——
+    // 后者在本仓 coding-steering 侧也是 `FORCE_FRAMEWORK_ENVIRONMENT=boe` 时默认取 `dev`。
+    //
+    // lane 必须压过 dev：TCC 里配了 tgz-key 就说明是定向灰度（钉某个 feat 分支的快照），
+    // 不能被"BOE 就跟 develop"这条默认规则覆盖掉。
+    const isBoe = process.env.FORCE_FRAMEWORK_ENVIRONMENT === 'boe';
+    const primaryVersion = laneVersion ?? (isBoe ? 'dev' : 'latest');
     try {
         (0, logger_1.debug)(`sandbox-skills: fetching ${packageName}@${primaryVersion}`);
         fetched = (0, npm_pack_1.fetchNpmPackage)({
@@ -138,6 +147,9 @@ function syncSandboxSkills(opts) {
         });
     }
     catch (err) {
+        // @latest 是最后一档，它再挂就没得降了，直接抛。
+        // lane / dev 拉失败都降到 @latest：dev 通道可能因为 develop 还没发过包而不存在
+        // （dist-tag 缺失 → npm pack 404），这时候不该让整条 sync 挂掉。
         if (primaryVersion === 'latest') {
             throw err;
         }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.31",
+  "version": "0.1.33-alpha.59a1bf2",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {