@lark-apaas/miaoda-cli 0.1.29 → 0.1.31

package/dist/config/migrate-configs/html-to-design-html.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * html → design-html 的跨 stack 迁移规则。
+ *
+ * html stack：应用文件在 src/（src/index.html 等），dev/build 走
+ * @lark-apaas/coding-html-devserver（devDependency + scripts.dev/build + package-lock）。
+ * design-html stack：buildless —— 文件直接放项目根（任意深度），无依赖、无 scripts，
+ * deploy 由 CLI 闭环（扫 *.html 生成 routes.json，见 services/deploy/modern/atoms/design-build）。
+ *
+ * 设计原则：**最小改动**。三件事 —— 布局搬迁、devserver 工具链清理、set-stack：
+ *   1. src/ 内容整体搬到项目根（merge：同名冲突 src/ 侧覆盖，搬完删 src/）
+ *   2. 清 devserver 残留：package-lock.json + package.json 的 dev/build scripts 与
+ *      coding-html-devserver devDependency（design-html 模板的 package.json 无任何
+ *      依赖 / scripts，用户其余自定义字段一律保留）
+ *   3. set-stack 切 .spark/meta.json（archType / templateVersion 由 handler 从
+ *      design-html template 包回写）
+ *
+ * 不做的事：
+ *   - 不从 design-html template 拷任何文件（模板本身只有 _gitignore + package.json；
+ *     用户已有的 .gitignore 是 html 版超集，保留无害）
+ *   - 不动 README.md / .npmrc / .env —— 部署时均被 EXCLUDES 过滤
+ *   - 不管 dev 进程 / MIAODA_APP_TYPE 切换（平台职责；沙箱 pkill 匹配的
+ *     scripts/dev.js 在 html 项目里不存在，自然跳过）
+ *
+ * handler 收尾的 npm install 照常跑：devserver 依赖删掉后重新生成精简 lockfile，
+ * 部署时被 EXCLUDES 过滤，无害；不为此引入 skip-install 能力。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIGRATE_CONFIG = void 0;
+exports.MIGRATE_CONFIG = {
+    from: 'html',
+    to: 'design-html',
+    rules: [
+        // ===== 1. 布局搬迁：src/ 内容整体搬到项目根 =====
+        // 目标 '.'（项目根）已存在 → 走 merge 分支：src/ 每个 entry overlay 到根，
+        // 同名冲突 src/ 侧覆盖，完成后删除 src/。相对引用路径不变。
+        { type: 'move-directory', from: 'src', to: '.' },
+        // ===== 2. 清理 devserver 工具链残留 =====
+        // 依赖集合变了（清空），lockfile 删掉由 handler 收尾的 npm install 重新生成
+        { type: 'delete-file', to: 'package-lock.json' },
+        {
+            type: 'delete-json-keys',
+            to: 'package.json',
+            keys: [
+                // coding-html-devserver 的 dev/build 入口，design-html 无 scripts
+                'scripts.dev',
+                'scripts.build',
+                // devserver 工具链本体
+                'devDependencies.@lark-apaas/coding-html-devserver',
+            ],
+        },
+        // ===== 3. 切 stack =====
+        { type: 'set-stack', stack: 'design-html' },
+    ],
+};
+exports.default = exports.MIGRATE_CONFIG;

package/dist/config/migrate-configs/index.js

@@ -18,9 +18,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getMigrateConfig = getMigrateConfig;
 exports.listSupportedMigrations = listSupportedMigrations;
 const vite_react_to_nestjs_react_fullstack_1 = __importDefault(require("./vite-react-to-nestjs-react-fullstack"));
+const html_to_design_html_1 = __importDefault(require("./html-to-design-html"));
 /** key 格式：`<from>:<to>` */
 const MIGRATE_REGISTRY = {
     'vite-react:nestjs-react-fullstack': vite_react_to_nestjs_react_fullstack_1.default,
+    'html:design-html': html_to_design_html_1.default,
 };
 /** 返回 (from, to) 对应的 MigrateConfig；未注册时返回 null。 */
 function getMigrateConfig(from, to) {

package/dist/services/app/init/template.js

@@ -37,11 +37,15 @@ exports.LOCAL_STEERING_STACKS = new Set(['nestjs-react-fullstack', 'vite-react']
 /**
  * app_type（业务类型）→ stack 短名映射。仅在调用方未显式传 --template 时用于解析 stack。
  * 与 src/api/app/types.ts 的 AppType 枚举无关，是独立的业务类型概念。
+ *
+ * 注：`frontend` 是 lark-cli 对外的纯前端应用类型；`jspage` 是内部历史代号，二者同映射
+ * 到 vite-react。保留 jspage 键以兼容内部既有调用方（豆包 / 妙搭链路），不删除。
  */
 exports.STACK_BY_APP_TYPE = {
     html: 'design-html',
     modern_html: 'html',
     jspage: 'vite-react',
+    frontend: 'vite-react',
     full_stack: 'nestjs-react-fullstack',
 };
 exports.APP_TYPES = Object.keys(exports.STACK_BY_APP_TYPE);

package/dist/services/deploy/modern/atoms/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.savePluginInstances = exports.LocalReleaseStatus = exports.finalizeLocalRelease = exports.createLocalRelease = exports.uploadArtifacts = exports.uploadDesignArtifacts = exports.cleanDesignDist = exports.buildDesignOutput = exports.runBuild = exports.preRelease = exports.prepareDeployContext = void 0;
+exports.savePluginInstances = exports.resolveReleaseTracker = exports.createManagedReleaseTracker = exports.NOOP_RELEASE_TRACKER = exports.LocalReleaseStatus = exports.finalizeLocalRelease = exports.createLocalRelease = exports.uploadArtifacts = exports.uploadDesignArtifacts = exports.cleanDesignDist = exports.buildDesignOutput = exports.runBuild = exports.preRelease = exports.prepareDeployContext = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "prepareDeployContext", { enumerable: true, get: function () { return context_1.prepareDeployContext; } });
 var pre_release_1 = require("./pre-release");
@@ -18,5 +18,9 @@ var local_release_1 = require("./local-release");
 Object.defineProperty(exports, "createLocalRelease", { enumerable: true, get: function () { return local_release_1.createLocalRelease; } });
 Object.defineProperty(exports, "finalizeLocalRelease", { enumerable: true, get: function () { return local_release_1.finalizeLocalRelease; } });
 Object.defineProperty(exports, "LocalReleaseStatus", { enumerable: true, get: function () { return local_release_1.LocalReleaseStatus; } });
+var release_tracker_1 = require("./release-tracker");
+Object.defineProperty(exports, "NOOP_RELEASE_TRACKER", { enumerable: true, get: function () { return release_tracker_1.NOOP_RELEASE_TRACKER; } });
+Object.defineProperty(exports, "createManagedReleaseTracker", { enumerable: true, get: function () { return release_tracker_1.createManagedReleaseTracker; } });
+Object.defineProperty(exports, "resolveReleaseTracker", { enumerable: true, get: function () { return release_tracker_1.resolveReleaseTracker; } });
 var save_plugin_instances_1 = require("./save-plugin-instances");
 Object.defineProperty(exports, "savePluginInstances", { enumerable: true, get: function () { return save_plugin_instances_1.savePluginInstances; } });

package/dist/services/deploy/modern/atoms/release-tracker.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOOP_RELEASE_TRACKER = void 0;
+exports.createManagedReleaseTracker = createManagedReleaseTracker;
+exports.resolveReleaseTracker = resolveReleaseTracker;
+const logger_1 = require("../../../../utils/logger");
+const local_release_1 = require("./local-release");
+/**
+ * 建本地发布单并返回受管 tracker。
+ *
+ * url 沿用原有口径：后端 onlineUrl 缺失时为空串（`''` 表示"后端没给"，
+ * 与外部托管模式的 `null`「本模式不产生」是两个不同语义，别合并）。
+ */
+async function createManagedReleaseTracker(appId, version, extra) {
+    (0, logger_1.log)('deploy', 'Creating local release...');
+    const release = await (0, local_release_1.createLocalRelease)(appId, version, extra);
+    return {
+        releaseID: release.releaseID,
+        url: release.onlineUrl ?? '',
+        finish: () => (0, local_release_1.finalizeLocalRelease)(appId, release.releaseID, local_release_1.LocalReleaseStatus.Finished),
+        fail: () => (0, local_release_1.finalizeLocalRelease)(appId, release.releaseID, local_release_1.LocalReleaseStatus.Failed),
+    };
+}
+/**
+ * 空实现：发布单由外部托管，CLI 不建单也不翻终态。
+ *
+ * 外部据 CLI 的退出码决定把自己的发布单翻成 Finished 还是 Failed，
+ * 因此这里的 finish/fail 必须是真正的 no-op，不能顺手打日志误导排查。
+ */
+exports.NOOP_RELEASE_TRACKER = {
+    releaseID: null,
+    url: null,
+    finish: () => Promise.resolve(),
+    fail: () => Promise.resolve(),
+};
+/** 按 skipRelease 选 tracker：跳过则 NOOP，否则建真实发布单。 */
+async function resolveReleaseTracker(opts) {
+    if (opts.skipRelease) {
+        (0, logger_1.log)('deploy', 'Skipping local release (managed externally)');
+        return exports.NOOP_RELEASE_TRACKER;
+    }
+    return createManagedReleaseTracker(opts.appId, opts.version, opts.extra);
+}

package/dist/services/deploy/modern/pipelines/design-local.js

@@ -24,25 +24,26 @@ async function designLocalPublishPipeline(opts) {
         if (!opts.skipBuild) {
             (0, index_1.buildDesignOutput)({ projectDir: ctx.projectDir });
         }
-        (0, logger_1.log)('deploy', 'Creating local release...');
-        const release = await (0, index_1.createLocalRelease)(ctx.appId, pre.version, {
-            checkPointVersion: opts.checkPointVersion,
-            commitID: opts.commitID,
+        const tracker = await (0, index_1.resolveReleaseTracker)({
+            skipRelease: opts.skipRelease ?? false,
+            appId: ctx.appId,
+            version: pre.version,
+            extra: { checkPointVersion: opts.checkPointVersion, commitID: opts.commitID },
         });
         try {
             await (0, index_1.uploadDesignArtifacts)({ projectDir: ctx.projectDir, data });
-            await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Finished);
+            await tracker.finish();
         }
         catch (err) {
-            await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Failed);
+            await tracker.fail();
             throw err;
         }
         (0, logger_1.log)('deploy', 'Deployed successfully');
         return {
             appId: ctx.appId,
             version: pre.version,
-            url: release.onlineUrl ?? '',
-            releaseID: release.releaseID,
+            url: tracker.url,
+            releaseID: tracker.releaseID,
             preReleaseID: pre.preReleaseID,
         };
     }

package/dist/services/deploy/modern/pipelines/local.js

@@ -11,14 +11,14 @@ const index_1 = require("../atoms/index");
  *   1. prepareDeployContext    — 校验项目 + 读 meta
  *   2. preRelease              — 签发 pre_release_id / version / 动态配置 data
  *   3. runBuild                — 本地 npm run build（注入 data 中的 CDN 前缀）
- *   4. createLocalRelease      — 创建发布单（加锁、拿 releaseID）
+ *   4. resolveReleaseTracker   — 创建发布单（加锁、拿 releaseID）；--skip-release 下为 NOOP
  *   5. uploadArtifacts         — 把产物推到 preRelease 下发的 pre-signed URL
  *   6. savePluginInstances     — 扫描 dist/output_capabilities/*.json，批量注册插件能力
- *   7. finalizeLocalRelease    — Finished / Failed 翻终态
+ *   7. tracker.finish/fail     — Finished / Failed 翻终态
  *
- * createLocalRelease 提前到 upload 之前：发布单先建出来，
- * upload / savePluginInstances 在已知 releaseID 的前提下进行；
+ * 发布单先于 upload 建出来：upload / savePluginInstances 在已知 releaseID 的前提下进行；
  * 任一步失败都会精准把该发布单标记为 Failed，避免遗留挂态。
+ * `--skip-release` 下发布单由外部托管，tracker 为 NOOP，失败信息通过非零退出码传递。
  */
 async function localBuildLocalPublishPipeline(opts) {
     const ctx = (0, index_1.prepareDeployContext)(opts.projectDir, opts.appId);
@@ -41,10 +41,11 @@ async function localBuildLocalPublishPipeline(opts) {
             data,
         });
     }
-    (0, logger_1.log)('deploy', 'Creating local release...');
-    const release = await (0, index_1.createLocalRelease)(ctx.appId, pre.version, {
-        checkPointVersion: opts.checkPointVersion,
-        commitID: opts.commitID,
+    const tracker = await (0, index_1.resolveReleaseTracker)({
+        skipRelease: opts.skipRelease ?? false,
+        appId: ctx.appId,
+        version: pre.version,
+        extra: { checkPointVersion: opts.checkPointVersion, commitID: opts.commitID },
     });
     try {
         (0, logger_1.log)('deploy', 'Uploading artifacts...');
@@ -57,18 +58,18 @@ async function localBuildLocalPublishPipeline(opts) {
         if (saveResult.saved > 0) {
             (0, logger_1.log)('deploy', `${String(saveResult.saved)} capability instance(s) registered`);
         }
-        await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Finished);
+        await tracker.finish();
     }
     catch (err) {
-        await (0, index_1.finalizeLocalRelease)(ctx.appId, release.releaseID, index_1.LocalReleaseStatus.Failed);
+        await tracker.fail();
         throw err;
     }
     (0, logger_1.log)('deploy', 'Deployed successfully');
     return {
         appId: ctx.appId,
         version: pre.version,
-        url: release.onlineUrl ?? '',
-        releaseID: release.releaseID,
+        url: tracker.url,
+        releaseID: tracker.releaseID,
         preReleaseID: pre.preReleaseID,
     };
 }

package/dist/services/registry/index.js

@@ -22,12 +22,13 @@ const logger_1 = require("../../utils/logger");
  *
  * registry 包按 **运行时（runtime）** 命名分发（而非 stack）：多个 stack 可共享同一 runtime
  * 的同一份 registry。runtime 不引入新的 meta 字段，从已有的 `.spark/meta.json.stack` 推得。
- *   STACK_RUNTIME:        stack → runtime（design-html 跑在 buildless 运行时）
+ *   STACK_RUNTIME:        stack → runtime（design-html / html 都跑在 buildless 运行时）
  *   REGISTRY_BY_RUNTIME:  runtime → registry 包名
  * 任一步查不到都明确报错（stack 无对应 runtime / runtime 无对应 registry）。
  */
 exports.STACK_RUNTIME = {
     'design-html': 'buildless',
+    html: 'buildless',
 };
 exports.REGISTRY_BY_RUNTIME = {
     buildless: '@lark-apaas/coding-registry-buildless',

package/dist/utils/coding-steering.js

@@ -63,6 +63,16 @@ function syncCodingSteering(opts) {
                 dstSkillsDir: node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack, 'skills'),
                 dstTechPath: node_path_1.default.join(opts.targetDir, '.agent', 'skills', 'steering', opts.stack, 'tech.md'),
             };
+        // **本函数不碰任何权限位**——解锁是调用方的事：
+        //   - 老链路：`update-skills.sh:162` 在跑一切之前统一 `chmod -R u+w "$TARGET_DIR"`
+        //   - 新链路（`skills sync --type X`）：同一次调用里 syncSandboxSkills 已经递归解锁过
+        //     整个 skills 根，本函数紧随其后执行，目录必然可写
+        //   - 本地 dev / `app init`：目录从来不会被锁
+        //
+        // 曾在这里加过「解锁 + 写完还原」，两个理由下掉：steering 子树的所有权明确归 CLI
+        // （老脚本 :179/:208 写明 `steering/ 子树由 miaoda CLI 独占，update.sh 不写不删`），
+        // 锁它没收益；而权限逻辑散在写入方会跟收尾的 lockDirReadonly 形成隐式耦合，
+        // 范围一旦不对称就会出「跑一次 skills sync 把整个 skills 目录解封」这种事。
         node_fs_1.default.mkdirSync(dstSkillsDir, { recursive: true });
         let techSynced = false;
         const techSrc = node_path_1.default.join(stackDir, 'tech.md');

package/dist/utils/devops-error.js

@@ -1,24 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BizErrCode = void 0;
 exports.mapDevopsError = mapDevopsError;
 const error_1 = require("./error");
+exports.BizErrCode = {
+    /** devops：应用不存在（含把非应用 ID 当 app-id 传入的情况） */
+    DEVOPS_APP_NOT_FOUND: '400002577',
+    /** devops：应用不存在（另一路径，与上同义） */
+    DEVOPS_APP_NOT_FOUND_ALT: '400002569',
+    /** devops：无应用权限 */
+    DEVOPS_APP_PERMISSION_DENIED: '400002579',
+    /** devops：参数非法（如 name / description 超长） */
+    DEVOPS_INVALID_ARG: '400002575',
+    /** studio_server：ErrUnauthenticated —— 身份换取失败或未通过资源鉴权 */
+    STUDIO_UNAUTHENTICATED: '400002671',
+    /** studio_server：ErrStudioAppNotFound —— meta_token 无效或未绑定妙搭应用 */
+    STUDIO_APP_NOT_FOUND: '400002667',
+};
 /**
  * 把 BAM lark.apaas.devops 的业务码（数字字符串）映射成 CLI 错误码。
- * 来源：服务端技术方案 wiki L7P8wlNQ5iyShLkxzlOcCo8LnTg「业务错误码映射表」。
  *
  * 放在 utils 下而不是某个具体 api 域里：app / deploy 都跑在 lark.apaas.devops
  * 这同一 PSM，业务码命名空间也共享；boundaries 规则又禁止 api 域间互引。
  */
 function mapDevopsError(bizCode, message) {
     switch (bizCode) {
-        case '400002577':
-        case '400002569':
+        case exports.BizErrCode.DEVOPS_APP_NOT_FOUND:
+        case exports.BizErrCode.DEVOPS_APP_NOT_FOUND_ALT:
             return new error_1.AppError('APP_NOT_FOUND', message, {
                 next_actions: ['Run `miaoda app list` to see available apps'],
             });
-        case '400002579':
+        case exports.BizErrCode.DEVOPS_APP_PERMISSION_DENIED:
             return new error_1.AppError('APP_PERMISSION_DENIED', message);
-        case '400002575':
+        case exports.BizErrCode.DEVOPS_INVALID_ARG:
             return new error_1.AppError('INVALID_ARG_VALUE', message, {
                 next_actions: ['缩短 --name / --description 后重试（后端有长度限制）'],
             });

package/dist/utils/file-ops.js

@@ -5,6 +5,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.removeLineFromFile = removeLineFromFile;
 exports.removeLineFromContent = removeLineFromContent;
+exports.unlockDirForWrite = unlockDirForWrite;
+exports.lockDirReadonly = lockDirReadonly;
+exports.forceRemove = forceRemove;
+const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const logger_1 = require("./logger");
@@ -43,3 +47,80 @@ function removeLineFromContent(content, pattern) {
         changed: filtered.length !== lines.length,
     };
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// 目录权限：沙箱 skill 目录被刻意锁成只读，写入前须解锁、写完须锁回。
+//
+// 背景：老 update-skills.sh 同步末尾 `chmod -R a=rX "$TARGET_DIR"`（:241）把
+// skills 锁成只读——skills 是平台下发的资产，不该被用户/agent 手改；下一轮同步
+// 开头再 `chmod -R u+w`（:162）统一解锁。目录 owner 是沙箱当前用户，虽无写位但
+// 有权改权限，所以不需要 sudo（沙箱容器带 no_new_privileges，sudo 本就被禁）。
+//
+// **解锁只做在「整棵树的接管者」那一层**：新链路里就是 syncSandboxSkills（它重写
+// 整个平铺层），对齐老脚本 :162 那一次统一解锁。写 steering 的 syncCodingSteering
+// 不碰权限 —— 它跑在同一次调用里、紧随 syncSandboxSkills 之后，目录已经可写；
+// 各写入方各自 chmod 会与收尾的 lockDirReadonly 形成隐式耦合，范围一旦不对称就会
+// 出「跑一次 skills sync 把整个 skills 目录解封」这种事。
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 解锁目录使其可写（`chmod -R u+w`）。
+ *
+ * 写入被只读锁保护的目录前必须调用，否则 `fs.cpSync` / `fs.rmSync` 报 EACCES。
+ * 只加 owner 写位、不动 g/o，与老链路一致。目录不存在直接返回 false（调用方
+ * 通常紧接着 mkdir）。失败只 debug 不抛：解锁是尽力而为，真写不进去让后续
+ * 写操作自己报错，错误信息更具体。
+ */
+function unlockDirForWrite(dir) {
+    if (!node_fs_1.default.existsSync(dir))
+        return false;
+    try {
+        (0, node_child_process_1.execFileSync)('chmod', ['-R', 'u+w', dir], { stdio: ['ignore', 'ignore', 'pipe'] });
+        return true;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`file-ops: chmod -R u+w ${dir} failed: ${err.message}`);
+        return false;
+    }
+}
+/**
+ * 把目录锁成只读（`chmod -R a=rX`），对齐 update-skills.sh:241。
+ *
+ * `a=rX`：所有人只读；`X` 是大写，只给目录和「原本已有执行位」的文件加 x，
+ * 不会把 SKILL.md 变成可执行。会连 owner 写位一并清掉，所以下一轮写入前必须
+ * {@link unlockDirForWrite}。
+ *
+ * **调用时机必须是全部写入完成之后**——锁上就写不进去了。
+ */
+function lockDirReadonly(dir) {
+    if (!node_fs_1.default.existsSync(dir))
+        return false;
+    try {
+        (0, node_child_process_1.execFileSync)('chmod', ['-R', 'a=rX', dir], { stdio: ['ignore', 'ignore', 'pipe'] });
+        return true;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`file-ops: chmod -R a=rX ${dir} failed: ${err.message}`);
+        return false;
+    }
+}
+/**
+ * 强制删除文件或目录，三层兜底：`chmod -R u+w` → `rm -rf` → `fs.rmSync`。
+ *
+ * 为什么不能直接 `fs.rmSync`：删条目需要**父目录**写权限，而 skill 目录常处于
+ * 只读锁下；另外老 update.sh 曾以 root 跑过，可能留下异主文件（如 root-owned 的
+ * `.last-update`），`rmSync{force:true}` 只忽略 ENOENT、遇 EACCES 仍抛。
+ * shell `rm -rf` 对异主文件 / 怪符号链接比 rmSync 宽容，故作主档。
+ */
+function forceRemove(target) {
+    if (!node_fs_1.default.existsSync(target))
+        return;
+    unlockDirForWrite(target);
+    try {
+        (0, node_child_process_1.execFileSync)('rm', ['-rf', target], { stdio: ['ignore', 'ignore', 'pipe'] });
+        if (!node_fs_1.default.existsSync(target))
+            return;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`file-ops: rm -rf ${target} failed: ${err.message}`);
+    }
+    node_fs_1.default.rmSync(target, { recursive: true, force: true });
+}

package/dist/utils/npm-pack.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickLaneVersion = pickLaneVersion;
 exports.fetchNpmPackage = fetchNpmPackage;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
@@ -11,6 +12,38 @@ const node_path_1 = __importDefault(require("node:path"));
 const error_1 = require("./error");
 const logger_1 = require("./logger");
 const DEFAULT_REGISTRY = 'https://registry.npmmirror.com/';
+/**
+ * 从 `npm view <pkg> versions --json` 里过滤出后缀 `-alpha.<X>` 的版本。
+ *
+ * 用于 sandbox-skills 新姿势（2026-08 迁离 lane-<X> dist-tag 之后）：
+ * publish-sandbox-skills.sh 每次发的版本号 = `<base>-alpha.<LANE>-<YYYYMMDDHHMMSS>`，
+ * TCC 里的 X = `<LANE>-<TIMESTAMP>` 全局唯一。反推侧过滤 versions 数组即可精确命中。
+ *
+ * **不 throw 是硬要求**（消费方 fallback @latest 依赖返回 null 判定）：
+ *   - `npm view` 网络挂、包不存在、metadata 解析失败 → 返回 null
+ *   - 无版本匹配 → 返回 null
+ *   - 多版本匹配（理论上不该发生，因 timestamp 精度到秒）→ 字符串排序取最大（timestamp 最大）
+ */
+function pickLaneVersion(packageName, X, registry) {
+    const reg = registry ?? process.env.MIAODA_NPM_REGISTRY ?? DEFAULT_REGISTRY;
+    const suffix = `-alpha.${X}`;
+    try {
+        const stdout = (0, node_child_process_1.execFileSync)('npm', ['view', packageName, 'versions', '--json', '--registry', reg], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        const versions = JSON.parse(stdout);
+        if (!Array.isArray(versions))
+            return null;
+        const matched = versions.filter((v) => typeof v === 'string' && v.endsWith(suffix));
+        if (matched.length === 0)
+            return null;
+        // 通常唯一命中（X 含 timestamp 到秒）；多命中时字符串排序取最大（timestamp 更晚）
+        matched.sort();
+        return matched[matched.length - 1] ?? null;
+    }
+    catch (err) {
+        (0, logger_1.debug)(`pickLaneVersion(${packageName}, X=${X}) failed: ${err.message}`);
+        return null;
+    }
+}
 /**
  * `npm pack <pkg>@<ver> --registry <r>` + `tar -xzf`，解到临时目录。
  * extractDir 是包内容根（含 package.json）。使用完必须 cleanup()。