@lark-apaas/fullstack-cli 1.1.62 → 1.1.63-alpha.20260825175418

package/dist/index.js

@@ -2617,15 +2617,7 @@ function emptyProfile() {
 }
 function viteReactProfile() {
   return {
-    sync: [
-      // 覆盖 scripts/build.sh（回溯 public/* → dist/output/ 的修复）
-      {
-        from: "templates/vite-react/build.sh",
-        to: "scripts/build.sh",
-        type: "file",
-        overwrite: true
-      }
-    ],
+    sync: [],
     permissions: {},
     activateGitHooks: true
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-cli",
-  "version": "1.1.62",
+  "version": "1.1.63-alpha.20260825175418",
   "description": "CLI tool for fullstack template management",
   "type": "module",
   "main": "dist/index.js",

package/templates/.gitignore.append

@@ -5,4 +5,3 @@
 # scripts/ directory is auto-generated
 # DO NOT modify manually
 scripts/
-

package/templates/scripts/build.sh

@@ -146,14 +146,21 @@ STEP_START=$(node -e "console.log(Date.now())")
 # 使用 mv 而非 cp：HTML 不能上传到公网 CDN，移走后 dist/client 中不再包含 HTML
 if [ -d "$DIST_DIR/client" ]; then
   mkdir -p "$DIST_DIR/dist/client"
-  # public 先进（顶层 client 打包被排除；server setBaseViewsDir + 中间件同源 serve）
-  if [ -d "$ROOT_DIR/client/public" ]; then
-    cp -R "$ROOT_DIR/client/public/." "$DIST_DIR/dist/client/"
-  fi
-  # 构建产物 HTML 随后 move，覆盖 public 里的同名文件（保证入口页是构建版，不被 public 静默覆盖）
   find "$DIST_DIR/client" -maxdepth 1 -name "*.html" -exec mv {} "$DIST_DIR/dist/client/" \;
 fi
 
+# 拷贝 shared/static → dist/shared/static
+# Nest server 生产从 process.cwd() + shared/static 读 (nestjs-core static.controller.ts:100),
+# 生产 cwd = dist/, 所以目标是 dist/shared/static。coding-preset 的 static-assets plugin
+# 之前 closeBundle 拷贝, 现在删除后交给 build.sh 显式做 (跟 jsPage 的 output_static rsync 对齐)。
+# 排除 .ts/.tsx/.js/.jsx: 避免 shared/static/ 里若有开发脚本被误传到生产。
+if [ -d "$ROOT_DIR/shared/static" ]; then
+  mkdir -p "$DIST_DIR/shared/static"
+  rsync -a --exclude='*.ts' --exclude='*.tsx' --exclude='*.js' --exclude='*.jsx' \
+    "$ROOT_DIR/shared/static/" "$DIST_DIR/shared/static/"
+  echo "   Static → dist/shared/static/"
+fi
+
 # server 相关产物准备（only_frontend_change=true 时跳过）
 if [[ "${only_frontend_change:-false}" == "true" ]]; then
   echo "   [skip] 跳过 run.sh/.env 复制 (only_frontend_change=true)"

package/templates/scripts/dev.js

@@ -252,20 +252,25 @@ process.on('SIGTERM', cleanup);
 process.on('SIGINT', cleanup);
 process.on('SIGHUP', cleanup);
 
-// Stale dist makes nest --watch skip missing files; watcher won't self-heal.
-function cleanStaleDist() {
-  const distPath = path.join(PROJECT_ROOT, 'dist');
-  if (fs.existsSync(distPath)) {
-    fs.rmSync(distPath, { recursive: true, force: true });
-    logEvent('INFO', 'main', 'Cleaned dist/ to force full rebuild');
-  }
-}
+// dist 缓存策略:
+//   沙箱首次启动 + dist 对应当前 lockfile → 保留 dist/, 让 nest --watch 复用上次编译产物
+//   沙箱首次启动 + dist 对应别的 lockfile → 清 dist/, 避免依赖换了却用旧产物 (stale binding)
+//   后续启动 (agent 主动触发 npm run dev) → 全清 dist/, 让模型面对新鲜产物避免 stale
+//   依赖升级 (lockfile hash 变) → 同后续启动 (清 dist), log 里点出 "deps changed"
+//   FORCE_CLEAN_DIST=true → escape hatch, 强清
+// marker 放 os.tmpdir()/.miaoda-dev-boot (跟沙箱容器 lifecycle 同, 沙箱重启会清空,
+// 语义对齐"沙箱首次启动"); "dist 对应哪份 lockfile" 另记在 dist/.miaoda-dist-lockfile,
+// 跟 dist 一起备份/恢复 —— 不能用 mtime 判, TOS 恢复会把 mtime 全部重写(详见该模块头注释)。
+// 具体逻辑抽到 lib/preserve-dev-cache.cjs 便于单测。
+const { preserveDevCache } = require('./lib/preserve-dev-cache.cjs');
 
 // ── Main ──────────────────────────────────────────────────────────────────────
 async function main() {
   logEvent('INFO', 'main', '========== Dev session started ==========');
 
-  cleanStaleDist();
+  preserveDevCache(PROJECT_ROOT, {
+    log: (level, msg) => logEvent(level, 'main', msg),
+  });
 
   // Initialize action plugins
   writeOutput('\n🔌 Initializing action plugins...\n');

package/templates/scripts/lib/__test__/preserve-dev-cache.test.ts

@@ -0,0 +1,463 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const { preserveDevCache } = require('../preserve-dev-cache.cjs');
+
+interface LogEntry {
+  level: string;
+  msg: string;
+}
+
+function makeLogger(entries: LogEntry[]) {
+  return (level: string, msg: string) => {
+    entries.push({ level, msg });
+  };
+}
+
+describe('preserveDevCache', () => {
+  let tmpDir: string;
+  let markerPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'preserve-dev-cache-'));
+    markerPath = path.join(tmpDir, '.miaoda-dev-boot-marker');
+  });
+
+  afterEach(() => {
+    try {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  describe('FORCE_CLEAN_DIST escape hatch', () => {
+    it('cleans dist and writes marker regardless of state', () => {
+      fs.mkdirSync(path.join(tmpDir, 'dist', 'server'), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-content');
+      const logs: LogEntry[] = [];
+
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger(logs),
+        forceClean: true,
+        markerPath,
+      });
+
+      expect(r.action).toBe('force_cleaned');
+      expect(fs.existsSync(path.join(tmpDir, 'dist'))).toBe(false);
+      expect(fs.existsSync(markerPath)).toBe(true);
+      expect(logs[0].msg).toContain('FORCE_CLEAN_DIST');
+    });
+  });
+
+  describe('first boot (no marker)', () => {
+    it('preserves existing dist and writes marker', () => {
+      fs.mkdirSync(path.join(tmpDir, 'dist', 'server'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, 'dist', 'server', 'main.js'),
+        'compiled-content'
+      );
+      const logs: LogEntry[] = [];
+
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger(logs),
+        forceClean: false,
+        markerPath,
+      });
+
+      expect(r.action).toBe('first_boot_preserved');
+      expect(fs.existsSync(path.join(tmpDir, 'dist', 'server', 'main.js'))).toBe(true);
+      expect(fs.existsSync(markerPath)).toBe(true);
+      expect(logs[0].msg).toContain('first boot');
+    });
+
+    it('handles no dist as first_boot_no_dist', () => {
+      const logs: LogEntry[] = [];
+
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger(logs),
+        forceClean: false,
+        markerPath,
+      });
+
+      expect(r.action).toBe('first_boot_no_dist');
+      expect(fs.existsSync(markerPath)).toBe(true);
+      expect(logs[0].msg).toContain('no dist/');
+    });
+
+    it('marker stores current lockfile hash', () => {
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'initial-lock');
+
+      preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+
+      const raw = fs.readFileSync(markerPath, 'utf-8');
+      const data = JSON.parse(raw);
+      expect(typeof data.lockfileHash).toBe('string');
+      expect(data.lockfileHash.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('subsequent boot (marker exists)', () => {
+    it('cleans dist and rewrites marker when lockfile unchanged', () => {
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-content');
+      preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+
+      fs.mkdirSync(path.join(tmpDir, 'dist', 'server'), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, 'dist', 'server', 'main.js'), 'stale');
+
+      const logs: LogEntry[] = [];
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger(logs),
+        forceClean: false,
+        markerPath,
+      });
+
+      expect(r.action).toBe('subsequent_boot_cleaned');
+      // 编译产物必须清空; dist/ 目录本身会留下 provenance(记录接下来针对哪份 lockfile 编译),
+      // 否则下次冷启动读不到 provenance,会退化成每次全清。
+      expect(fs.existsSync(path.join(tmpDir, 'dist', 'server'))).toBe(false);
+      expect(fs.existsSync(path.join(tmpDir, 'dist', '.miaoda-dist-lockfile'))).toBe(true);
+      expect(fs.existsSync(markerPath)).toBe(true);
+      expect(logs[0].msg).toContain('subsequent boot');
+    });
+
+    it('reports deps_changed when lockfile hash mismatches marker', () => {
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-v1');
+      preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-v2');
+      fs.mkdirSync(path.join(tmpDir, 'dist', 'server'), { recursive: true });
+
+      const logs: LogEntry[] = [];
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger(logs),
+        forceClean: false,
+        markerPath,
+      });
+
+      expect(r.action).toBe('deps_changed_cleaned');
+      expect(fs.existsSync(path.join(tmpDir, 'dist', 'server'))).toBe(false);
+      // provenance 换成新 lockfile 的 hash,下次冷启动才可能复用
+      expect(fs.existsSync(path.join(tmpDir, 'dist', '.miaoda-dist-lockfile'))).toBe(true);
+      expect(logs[0].msg).toContain('deps changed');
+    });
+
+    it('reports subsequent_boot_no_dist when marker exists but no dist', () => {
+      preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+
+      const logs: LogEntry[] = [];
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger(logs),
+        forceClean: false,
+        markerPath,
+      });
+
+      expect(r.action).toBe('subsequent_boot_no_dist');
+      expect(fs.existsSync(markerPath)).toBe(true);
+      expect(logs[0].msg).toContain('no dist/');
+    });
+  });
+
+  describe('lockfile detection', () => {
+    it('supports package-lock.json', () => {
+      fs.writeFileSync(path.join(tmpDir, 'package-lock.json'), '{}');
+      preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+
+      const raw = fs.readFileSync(markerPath, 'utf-8');
+      expect(JSON.parse(raw).lockfileHash).not.toBeNull();
+    });
+
+    it('supports pnpm-lock.yaml', () => {
+      fs.writeFileSync(path.join(tmpDir, 'pnpm-lock.yaml'), 'lockfileVersion: 9');
+      preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+
+      const raw = fs.readFileSync(markerPath, 'utf-8');
+      expect(JSON.parse(raw).lockfileHash).not.toBeNull();
+    });
+
+    it('stores null lockfileHash when no lockfile present', () => {
+      preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+
+      const raw = fs.readFileSync(markerPath, 'utf-8');
+      expect(JSON.parse(raw).lockfileHash).toBeNull();
+    });
+  });
+
+  describe('first boot dist staleness (lockfile content hash)', () => {
+    const PROVENANCE = '.miaoda-dist-lockfile';
+
+    /**
+     * 复刻生产侧 computeLockfileHash 的口径: 文件名 + 内容一起 hash。
+     * 这里的用例统一只用 yarn.lock,所以固定带该文件名。
+     */
+    function lockHash(content: string, name = 'yarn.lock') {
+      return crypto.createHash('sha1').update(name).update(content).digest('hex');
+    }
+
+    /** 造一个"已编译过"的 dist,可选带上 provenance 记录它针对哪份 lockfile 内容 */
+    function makeDist(builtAgainstLockContent: string | null) {
+      fs.mkdirSync(path.join(tmpDir, 'dist', 'server'), { recursive: true });
+      // main.js 是生产侧判定"有编译产物"的入口,不能换成别的文件名
+      fs.writeFileSync(path.join(tmpDir, 'dist', 'server', 'main.js'), 'compiled');
+      if (builtAgainstLockContent !== null) {
+        fs.writeFileSync(
+          path.join(tmpDir, 'dist', PROVENANCE),
+          JSON.stringify({ lockfileHash: lockHash(builtAgainstLockContent) })
+        );
+      }
+    }
+
+    it('preserves dist when provenance matches current lockfile', () => {
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-v1');
+      makeDist('lock-v1');
+
+      const logs: LogEntry[] = [];
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger(logs),
+        forceClean: false,
+        markerPath,
+      });
+
+      expect(r.action).toBe('first_boot_preserved');
+      expect(fs.existsSync(path.join(tmpDir, 'dist', 'server', 'main.js'))).toBe(true);
+      expect(logs[0].msg).toContain('preserved');
+    });
+
+    it('cleans dist when provenance records a different lockfile', () => {
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-v2');
+      makeDist('lock-v1');
+
+      const logs: LogEntry[] = [];
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger(logs),
+        forceClean: false,
+        markerPath,
+      });
+
+      expect(r.action).toBe('first_boot_deps_changed_cleaned');
+      expect(fs.existsSync(path.join(tmpDir, 'dist', 'server', 'main.js'))).toBe(false);
+      expect(logs[0].msg).toContain('deps changed');
+    });
+
+    it('cleans dist when provenance is missing (pre-existing dist, cannot verify)', () => {
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-v1');
+      makeDist(null);
+
+      const logs: LogEntry[] = [];
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger(logs),
+        forceClean: false,
+        markerPath,
+      });
+
+      expect(r.action).toBe('first_boot_unverifiable_cleaned');
+      expect(fs.existsSync(path.join(tmpDir, 'dist', 'server', 'main.js'))).toBe(false);
+      expect(logs[0].msg).toContain('provenance missing');
+    });
+
+    it('preserves dist when no lockfile present (nothing to verify against)', () => {
+      makeDist(null);
+
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+
+      expect(r.action).toBe('first_boot_preserved');
+      expect(fs.existsSync(path.join(tmpDir, 'dist', 'server', 'main.js'))).toBe(true);
+    });
+
+    // 回归:这是 mtime 方案在 BOE 上 100% 失效的场景(2026-08-25 实测 2/2 冷启动)。
+    // 沙箱冷启动从 TOS 备份恢复 workspace 时会把所有文件 mtime 重写成恢复时刻,
+    // lockfile 稳定落在 dist/ 之后 → 旧的 `lockfile mtime > buildinfo mtime` 恒成立 →
+    // 每次都清 dist。依赖内容没变时必须复用,无论 mtime 谁新谁旧。
+    it('preserves dist even when lockfile mtime is newer than everything in dist', () => {
+      makeDist('lock-v1');
+      // 显式把 lockfile 的 mtime 推到未来,模拟恢复后 lockfile 比 dist 内所有文件都"新"
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-v1');
+      const future = new Date(Date.now() + 60_000);
+      fs.utimesSync(path.join(tmpDir, 'yarn.lock'), future, future);
+
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+
+      expect(r.action).toBe('first_boot_preserved');
+      expect(fs.existsSync(path.join(tmpDir, 'dist', 'server', 'main.js'))).toBe(true);
+    });
+
+    it('writes provenance after cleaning so the next cold boot can reuse', () => {
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-v1');
+      makeDist(null);
+
+      // 第一次冷启动:无 provenance → 清一次(迁移成本)
+      const first = preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+      expect(first.action).toBe('first_boot_unverifiable_cleaned');
+
+      // 模拟随后的编译产出,并模拟沙箱重启(marker 消失)
+      fs.mkdirSync(path.join(tmpDir, 'dist', 'server'), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, 'dist', 'server', 'main.js'), 'compiled');
+      fs.unlinkSync(markerPath);
+
+      // 第二次冷启动:provenance 已在,依赖没变 → 复用
+      const second = preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+      expect(second.action).toBe('first_boot_preserved');
+      expect(fs.existsSync(path.join(tmpDir, 'dist', 'server', 'main.js'))).toBe(true);
+    });
+
+    it('treats a dist holding only provenance as no dist', () => {
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-v1');
+      fs.mkdirSync(path.join(tmpDir, 'dist'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tmpDir, 'dist', PROVENANCE),
+        JSON.stringify({ lockfileHash: lockHash('lock-v1') })
+      );
+
+      const logs: LogEntry[] = [];
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger(logs),
+        forceClean: false,
+        markerPath,
+      });
+
+      // provenance 匹配但没有真实产物,不能谎报 preserved
+      expect(r.action).toBe('first_boot_no_dist');
+      expect(logs[0].msg).toContain('no dist/');
+    });
+
+    // 新建应用的标准生命周期:首次进 dev 时 marker 和 dist 都没有。
+    // 这一分支若不写 provenance,每个应用的**首次冷启动**都必然复用失败。
+    it('records provenance on a brand-new project so its first cold boot can reuse', () => {
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-v1');
+
+      const first = preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+      expect(first.action).toBe('first_boot_no_dist');
+
+      // 编译产出 + 沙箱重启
+      fs.mkdirSync(path.join(tmpDir, 'dist', 'server'), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, 'dist', 'server', 'main.js'), 'compiled');
+      fs.unlinkSync(markerPath);
+
+      const second = preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+      expect(second.action).toBe('first_boot_preserved');
+    });
+
+    // 多种 lockfile 共存时,只 hash 第一个会让另一个的依赖变更完全隐形 —— 原 mtime 方案
+    // 取的是所有 lockfile 的 max(mtime),换成 hash 不能反而把守护面变窄。
+    it('detects dependency changes in any lockfile when several coexist', () => {
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'yarn-lock-stable');
+      fs.writeFileSync(path.join(tmpDir, 'package-lock.json'), '{"v":1}');
+      fs.mkdirSync(path.join(tmpDir, 'dist', 'server'), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, 'dist', 'server', 'main.js'), 'compiled');
+
+      // 第一次:无 provenance → 清一次并写入当前(两个 lockfile 的)组合 hash
+      preserveDevCache(tmpDir, { log: makeLogger([]), forceClean: false, markerPath });
+      // 模拟随后的编译产出(上一步把 dist 清了)
+      fs.mkdirSync(path.join(tmpDir, 'dist', 'server'), { recursive: true });
+      fs.writeFileSync(path.join(tmpDir, 'dist', 'server', 'main.js'), 'compiled');
+
+      // 依赖没变 → 应当复用,确认基线正常
+      fs.unlinkSync(markerPath);
+      const baseline = preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+      expect(baseline.action).toBe('first_boot_preserved');
+
+      // 只改 package-lock.json(yarn.lock 不动) → 必须被识别为依赖变更
+      fs.writeFileSync(path.join(tmpDir, 'package-lock.json'), '{"v":2}');
+      fs.unlinkSync(markerPath);
+      const afterNpmInstall = preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+        markerPath,
+      });
+      expect(afterNpmInstall.action).toBe('first_boot_deps_changed_cleaned');
+    });
+
+    it('stores the current lockfile hash into provenance when cleaning', () => {
+      fs.writeFileSync(path.join(tmpDir, 'yarn.lock'), 'lock-v2');
+      makeDist('lock-v1');
+
+      preserveDevCache(tmpDir, { log: makeLogger([]), forceClean: false, markerPath });
+
+      // 断言内容而非仅存在: 写成 prevLockfileHash 之类也能让"文件存在"通过
+      const written = JSON.parse(
+        fs.readFileSync(path.join(tmpDir, 'dist', PROVENANCE), 'utf-8')
+      );
+      expect(written.lockfileHash).toBe(lockHash('lock-v2'));
+    });
+  });
+
+  describe('marker path (sandbox lifecycle alignment)', () => {
+    it('defaults markerPath to os.tmpdir()/.miaoda-dev-boot when not passed', () => {
+      // 不传 markerPath, 走默认路径
+      const defaultMarker = path.join(os.tmpdir(), '.miaoda-dev-boot');
+      // 清理默认位置的残留 marker (可能来自其他测试),避免干扰本用例
+      try { fs.unlinkSync(defaultMarker); } catch { /* noop */ }
+
+      const r = preserveDevCache(tmpDir, {
+        log: makeLogger([]),
+        forceClean: false,
+      });
+
+      expect(r.action).toBe('first_boot_no_dist');
+      expect(fs.existsSync(defaultMarker)).toBe(true);
+
+      // cleanup
+      try { fs.unlinkSync(defaultMarker); } catch { /* noop */ }
+    });
+  });
+});

package/templates/scripts/lib/preserve-dev-cache.cjs

@@ -0,0 +1,262 @@
+'use strict';
+
+// dev.js 启动时的 dist 缓存策略:
+//  - 沙箱首次启动 (marker 不存在) + dist 是针对当前依赖编译的: 保留 dist/, 让 nest --watch 复用上次编译产物
+//  - 沙箱首次启动 + dist 对不上当前依赖 (或无从判断): 清 dist/, 避免 stale binding
+//  - 后续启动 (agent 主动触发 npm run dev): 全清 dist/, 让模型面对新鲜产物避免 stale
+//  - FORCE_CLEAN_DIST=true: escape hatch, 强清且不留 provenance
+//
+// 两个状态文件, 各回答一个问题:
+//
+//  1. marker (os.tmpdir()/.miaoda-dev-boot) —— "这是不是沙箱首次启动"
+//     放 /tmp 是因为它跟容器 lifecycle 同生命周期: 沙箱重启 /tmp 被清, marker 消失,
+//     下次进 dev 即视为首次启动。应用工作目录是 persistent volume, 跨重启保留,
+//     放那里的 marker 反映不了"沙箱首次启动"。
+//
+//  2. provenance (dist/.miaoda-dist-lockfile) —— "当前 dist 是针对哪份 lockfile 编译的"
+//     内容是所有 lockfile 的内容 hash。放 dist/ 内部, 跟 dist 一起备份/恢复/被清,
+//     不会出现"dist 没了 hash 还在"的悬挂状态; 模板 .gitignore 已忽略 dist/。
+//
+// 首次启动分支判 stale 必须用内容 hash, **不能用 mtime**: 沙箱冷启动是
+// "销毁 → 从备份恢复 workspace", 恢复会把所有文件 mtime 重写成恢复时刻, 彼此只差
+// 几毫秒且先后由解包顺序决定 —— lockfile 与 buildinfo 的新旧关系在恢复后已无意义,
+// 用 mtime 判会稳定误判为 stale, 使 dist 复用在冷启动这个唯一目标场景里失效。
+// 内容 hash 不受恢复影响, 也顺带避免 `git checkout` touch lockfile 但内容没变的误判。
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const MARKER_FILENAME = '.miaoda-dev-boot';
+// 记录"当前 dist 是针对哪份 lockfile 编译的"
+const DIST_PROVENANCE_FILENAME = '.miaoda-dist-lockfile';
+
+/**
+ * @param {string} projectRoot 项目根目录
+ * @param {object} [options]
+ * @param {(level: string, msg: string) => void} [options.log]
+ * @param {boolean} [options.forceClean]
+ * @param {string} [options.markerPath] 覆盖 marker 文件路径 (单测用; 生产默认 /tmp/.miaoda-dev-boot)
+ * @returns {{ action: 'force_cleaned' | 'first_boot_preserved' | 'first_boot_deps_changed_cleaned' | 'first_boot_unverifiable_cleaned' | 'first_boot_no_dist' | 'subsequent_boot_cleaned' | 'deps_changed_cleaned' | 'subsequent_boot_no_dist' }}
+ */
+function preserveDevCache(projectRoot, options) {
+  const log = (options && options.log) || defaultLogger;
+  const forceClean =
+    options && typeof options.forceClean === 'boolean'
+      ? options.forceClean
+      : process.env.FORCE_CLEAN_DIST === 'true';
+  const markerPath =
+    (options && options.markerPath) ||
+    path.join(os.tmpdir(), MARKER_FILENAME);
+
+  const distPath = path.join(projectRoot, 'dist');
+  const currentLockfileHash = computeLockfileHash(projectRoot);
+
+  if (forceClean) {
+    // escape hatch 的语义是"彻底擦干净", 所以连 provenance 也不留 —— 下次冷启动
+    // 因此会多清一次 dist, 这正是显式要求强清的人期望的保守方向。
+    cleanDist(distPath);
+    writeMarker(markerPath, currentLockfileHash);
+    log('INFO', 'preserveDevCache: FORCE_CLEAN_DIST=true, cleaned dist/');
+    return { action: 'force_cleaned' };
+  }
+
+  const markerExists = fs.existsSync(markerPath);
+  const distExists = distHasBuildOutput(distPath);
+
+  if (!markerExists) {
+    writeMarker(markerPath, currentLockfileHash);
+    if (distExists) {
+      // 无 lockfile 时无从判断 dist 针对哪份依赖, 保守保留(与"依赖没变"同解),
+      // 免得没有依赖管理的项目每次冷启动都白白全量重编。
+      if (currentLockfileHash === null) {
+        log('INFO', 'preserveDevCache: first boot, no lockfile to verify against, dist/ preserved');
+        return { action: 'first_boot_preserved' };
+      }
+
+      const distLockfileHash = readDistProvenance(distPath);
+      // 日志带上两个 hash: 判错时能一眼区分"依赖真变了"和"读不到 provenance",
+      // 否则这类误判在现场完全不可观测。
+      const hashes = `dist=${short(distLockfileHash)} cur=${short(currentLockfileHash)}`;
+
+      if (distLockfileHash === currentLockfileHash) {
+        log('INFO', `preserveDevCache: first boot, dist/ matches current lockfile, preserved (${hashes})`);
+        return { action: 'first_boot_preserved' };
+      }
+
+      cleanDist(distPath);
+      writeDistProvenance(distPath, currentLockfileHash);
+
+      if (distLockfileHash === null) {
+        // 没有 provenance: dist 来自不带 provenance 机制的旧产物, 或刚被 npm run build
+        // 换成发布产物(build.sh 会 rm -rf dist)。都无从确认它针对哪份依赖 → 保守清一次;
+        // 清完写入 provenance, 下一次冷启动即可复用。
+        log(
+          'INFO',
+          `preserveDevCache: first boot but dist provenance missing (cannot verify deps), cleaned dist/ (${hashes})`
+        );
+        return { action: 'first_boot_unverifiable_cleaned' };
+      }
+      log(
+        'INFO',
+        `preserveDevCache: first boot but deps changed (dist built against a different lockfile), cleaned dist/ (${hashes})`
+      );
+      return { action: 'first_boot_deps_changed_cleaned' };
+    }
+    // 同样要写 provenance: 接下来编译出的 dist 就是针对当前 lockfile 的。
+    // 漏掉这里会让每个应用的**首次冷启动**必然复用失败 —— 新建应用第一次进 dev 走的正是
+    // 本分支(marker 无、dist 无), 若不记 provenance, 下次冷启动读不到就得保守全清。
+    writeDistProvenance(distPath, currentLockfileHash);
+    log('INFO', 'preserveDevCache: first boot, no dist/ (will be created)');
+    return { action: 'first_boot_no_dist' };
+  }
+
+  // 后续启动: 无脑清 dist
+  const prevLockfileHash = readMarkerHash(markerPath);
+  const depsChanged =
+    prevLockfileHash !== null &&
+    currentLockfileHash !== null &&
+    prevLockfileHash !== currentLockfileHash;
+
+  cleanDist(distPath);
+  // 清完就把 provenance 写回: 接下来的编译是针对当前 lockfile 的, 下次冷启动
+  // 才有依据判断能不能复用。不写的话首次启动分支永远读不到 provenance, 退化成每次全清。
+  writeDistProvenance(distPath, currentLockfileHash);
+  writeMarker(markerPath, currentLockfileHash);
+
+  if (depsChanged) {
+    log('INFO', 'preserveDevCache: deps changed (lockfile hash), cleaned dist/');
+    return { action: 'deps_changed_cleaned' };
+  }
+  if (distExists) {
+    log('INFO', 'preserveDevCache: subsequent boot, cleaned dist/');
+    return { action: 'subsequent_boot_cleaned' };
+  }
+  log('INFO', 'preserveDevCache: subsequent boot, no dist/ to clean');
+  return { action: 'subsequent_boot_no_dist' };
+}
+
+/**
+ * dist/ 里是否有真实编译产物。
+ *
+ * 判据用 server 入口而不是"目录非空": 清完 dist 会留下 provenance, 发布流程还会留下
+ * dist/node_modules、dist/dist 之类,靠"非空"会把这些空壳当成有产物 → 日志谎报 preserved。
+ * server/main.js 是 run.sh 实际启动的入口, 它在才算真编译过 —— 顺带让"编译中途失败"
+ * 留下的半成品被识别为无产物, 而不是被当成可复用。
+ *
+ * 出错方向偏向"有产物": 只有 ENOENT 才算真没有。EACCES / ENOTDIR 等情况下返回 false
+ * 会直接跳过清理分支, 让一个该清的 stale dist 被静默留下 —— 宁可多清一次。
+ */
+function distHasBuildOutput(distPath) {
+  try {
+    fs.statSync(path.join(distPath, 'server', 'main.js'));
+    return true;
+  } catch (err) {
+    return !(err && err.code === 'ENOENT');
+  }
+}
+
+function cleanDist(distPath) {
+  if (fs.existsSync(distPath)) {
+    fs.rmSync(distPath, { recursive: true, force: true });
+  }
+}
+
+function readDistProvenance(distPath) {
+  try {
+    const raw = fs.readFileSync(
+      path.join(distPath, DIST_PROVENANCE_FILENAME),
+      'utf-8'
+    );
+    const data = JSON.parse(raw);
+    return typeof data.lockfileHash === 'string' ? data.lockfileHash : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 记下"接下来编译出的 dist 是针对这份 lockfile 的"。
+ *
+ * 在 preserveDevCache 决策时写, 而不是等编译完 —— 此处没有编译完成的 hook。
+ * 因此 provenance 表达的是"接下来要针对哪份 lockfile 编译", 而非"已经编译完了"。
+ *
+ * 编译中途失败/被打断时它仍声称匹配, 但不会放大成 stale binding, 有三层理由:
+ *  1. 清理发生在写 provenance 之前, 所以残留一定是"新依赖的半成品", 不可能是"旧依赖的产物" ——
+ *     本模块要防的类别没被打开;
+ *  2. server/main.js 缺失时 distHasBuildOutput 判为无产物, 半成品走 no_dist 分支而不是被复用;
+ *  3. tsbuildinfo 就在 dist 内, 与产物同清同留, 不会出现"buildinfo 说完整、产物却缺"的错配。
+ */
+function writeDistProvenance(distPath, lockfileHash) {
+  try {
+    fs.mkdirSync(distPath, { recursive: true });
+    fs.writeFileSync(
+      path.join(distPath, DIST_PROVENANCE_FILENAME),
+      JSON.stringify({ lockfileHash: lockfileHash ?? null }),
+      'utf-8'
+    );
+  } catch {
+    // provenance 写失败只会让下次冷启动多清一次 dist, 不阻塞 dev 启动
+  }
+}
+
+/**
+ * 把项目里**所有**存在的 lockfile 一起 hash。
+ *
+ * 不能只取第一个命中的: 多种 lockfile 共存时(如历史残留 yarn.lock + 沙箱实际在用的
+ * package-lock.json), 只 hash 前者会让 `npm install pkg@2` 完全不改变 hash →
+ * 冷启动判"依赖没变"→ 保留旧依赖编译的 dist, 正是本模块要防的 stale binding。
+ * 原 mtime 方案取的是所有 lockfile 的 max(mtime), 对这种组合是免疫的, 换 hash 不能反而变窄。
+ * 文件名也一起 hash, 这样"删掉一个 lockfile"也算依赖变动。
+ */
+function computeLockfileHash(projectRoot) {
+  const candidates = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'];
+  const hash = crypto.createHash('sha1');
+  let found = false;
+  for (const name of candidates) {
+    try {
+      const content = fs.readFileSync(path.join(projectRoot, name));
+      hash.update(name);
+      hash.update(content);
+      found = true;
+    } catch {
+      // 该 lockfile 不存在 / 读不了, 跳过
+    }
+  }
+  return found ? hash.digest('hex') : null;
+}
+
+function readMarkerHash(markerPath) {
+  try {
+    const raw = fs.readFileSync(markerPath, 'utf-8');
+    const data = JSON.parse(raw);
+    return typeof data.lockfileHash === 'string' ? data.lockfileHash : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeMarker(markerPath, lockfileHash) {
+  try {
+    fs.writeFileSync(
+      markerPath,
+      JSON.stringify({ lockfileHash: lockfileHash ?? null }),
+      'utf-8'
+    );
+  } catch {
+    // marker 写失败下次会重试, 不阻塞 dev 启动
+  }
+}
+
+/** hash 只取前 8 位进日志, 够区分且不刷屏; null 显式打成 none 而不是空 */
+function short(hash) {
+  return typeof hash === 'string' ? hash.slice(0, 8) : 'none';
+}
+
+function defaultLogger(level, msg) {
+  // eslint-disable-next-line no-console
+  console.log(`[${level}] [main] ${msg}`);
+}
+
+module.exports = { preserveDevCache };

package/templates/vite-react/build.sh

@@ -1,61 +0,0 @@
-#!/bin/bash
-set -e
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-OUTPUT="$ROOT/dist/output"
-OUTPUT_RESOURCE="$ROOT/dist/output_resource"
-OUTPUT_STATIC="$ROOT/dist/output_static"
-
-# 映射平台环境变量到 preset 期望的变量名
-#   MIAODA_APP_ID            → /app/<appId> 作为客户端 base path
-#   MIAODA_RESOURCE_CDN_PREFIX → assets (JS/CSS) 的 CDN 前缀
-# CLI 注入约定见 miaoda-cli src/services/deploy/modern/atoms/build.ts
-export CLIENT_BASE_PATH="${MIAODA_APP_ID:+/app/$MIAODA_APP_ID}"
-export ASSETS_CDN_PATH="${MIAODA_RESOURCE_CDN_PREFIX:-/}"
-export STATIC_ASSETS_BASE_URL="${MIAODA_STATIC_CDN_PREFIX}"
-export NODE_ENV="${NODE_ENV:-production}"
-
-# 清理
-rm -rf "$ROOT/dist"
-
-# 1. Vite 构建 → dist/client/（相对于项目根目录输出）
-npx vite build --outDir "$ROOT/dist/client" --emptyOutDir
-
-# 2. public/ 静态资源 + HTML → dist/output/（模型 B：public = 应用根目录，同源 /app/<appId>/*）
-mkdir -p "$OUTPUT"
-# 2a. public/*：vite copyPublicDir 已把 public/* 平铺进 dist/client，但下面白名单只取
-#     *.html/routes.json，其余（favicon / 图片 / 运行时 fetch 的数据文件）会随 dist/client 被删。
-#     从源 public/ 补拷到 output/（同源根），让 fetch('/x') / resolveAppUrl('/x') 线上可用。
-#     先拷 public、再拷 HTML，保证构建产出的 index.html/routes.json 覆盖 public 里的同名文件（若有）。
-if [ -d "$ROOT/public" ]; then
-  cp -R "$ROOT/public/." "$OUTPUT/"
-fi
-# 2b. HTML + routes.json（构建产物）
-find "$ROOT/dist/client" -maxdepth 1 \( -name '*.html' -o -name 'routes.json' \) -exec cp {} "$OUTPUT/" \;
-
-# 3. assets/ → dist/output_resource/（JS/CSS/字体，上传到 CDN）
-if [ -d "$ROOT/dist/client/assets" ]; then
-  mkdir -p "$OUTPUT_RESOURCE"
-  cp -r "$ROOT/dist/client/assets" "$OUTPUT_RESOURCE/"
-fi
-
-# 4. 私有静态资源 → dist/output_static/（排除代码文件）
-if [ -d "$ROOT/shared/static" ]; then
-  mkdir -p "$OUTPUT_STATIC"
-  rsync -a --exclude='*.ts' --exclude='*.tsx' --exclude='*.js' --exclude='*.jsx' "$ROOT/shared/static/" "$OUTPUT_STATIC/"
-fi
-
-# 5. capability 配置 → dist/output_capabilities/
-if [ -d "$ROOT/shared/capabilities" ]; then
-  mkdir -p "$ROOT/dist/output_capabilities"
-  cp -r "$ROOT/shared/capabilities/." "$ROOT/dist/output_capabilities/"
-fi
-
-# 清理中间产物
-rm -rf "$ROOT/dist/client"
-
-echo "Build complete"
-echo "  HTML         → dist/output/"
-[ -d "$OUTPUT_RESOURCE" ] && echo "  Resource     → dist/output_resource/" || true
-[ -d "$OUTPUT_STATIC" ] && echo "  Static       → dist/output_static/" || true
-[ -d "$ROOT/dist/output_capabilities" ] && echo "  Capabilities → dist/output_capabilities/" || true