@coze-arch/cli 0.1.8-alpha.6e99f9 → 0.1.8-alpha.7654a3

package/README.md

@@ -42,6 +42,20 @@ coze-dev validate  # 读取 dev.validate
 `dev` 和 `build` 在执行前会尝试应用模板补丁；补丁失败会记录调试信息，但不会阻止主命令。
 子进程日志默认写入 `~/.coze-logs/dev.log`，可用 `--log-file <path>` 覆盖。
 
+## Web 云盘开发
+
+Vite、Next.js、Nuxt 的 Unix 开发 wrapper 在 `COZE_DRIVE_ROOT`（默认 `/Coze/Drive`）内通过
+`rsync` 同步源码到本机临时目录 `coze-web-<uid>/<source-path-hash>/`，再安装依赖和执行。
+`prepare/dev` 使用 `dev` 子目录，`validate` 使用独立的 `check` 子目录，避免类型生成干扰热更新。
+依赖和开发编译产物留在本地；只有安装成功且云盘依赖输入未变化时才回写锁文件。所有修复仍在云盘完成。
+dev 的 detached 进程持续同步，框架只监听本地镜像；同步失败或依赖输入变化时停止服务。
+
+本地镜像仅用于 `[dev].build/run/validate`；部署配置、`build.sh` 和 `start.sh` 保持原流程。
+普通本地目录和 Windows PowerShell 入口保持原流程。`rsync` 由开发环境提供，`[dev].deps` 仅作声明。
+存量项目通过 `coze-dev patch --dry-run` / `coze-dev patch` 升级，沿用 patch 总开关。
+仅升级完整匹配旧模板的三个 Unix 开发脚本并保留端口；自定义开发脚本、命令和同名 helper 会跳过。
+只更新开发插件不会替换存量项目脚本。
+
 ## Windows 与 WSL
 
 原生 Windows（`process.platform === "win32"`）优先使用 `.coze` 中非空的 Windows
@@ -106,3 +120,7 @@ npm run build
 ```
 
 端到端模板验证使用 `npm run test:e2e`，会真实安装模板依赖并启动服务。发布前需完成该验证。
+
+Web 镜像集成测试使用 `npm run test:integration:web`，依赖 Node.js、bash、rsync 和临时
+loopback 监听权限；包管理器和框架命令使用替身，验证目录、同步、锁文件与进程生命周期，
+不替代真实框架 E2E。

package/lib/__templates__/expo/.cozeproj/scripts/prepare-node-modules.sh

@@ -119,9 +119,7 @@ cleanup_legacy_workspace() {
   done < <(find "$workspace_dir" -mindepth 1 -maxdepth 1 -print0)
 }
 
-# caches is reserved for the sibling prepare scripts of this project. They keep
-# regenerable framework output there (the Next helper points .next/dev into it), and that
-# output has to outlive an install, so this cleanup must not read it as leftover.
+# Preserve existing project caches during dependency preparation.
 cleanup_legacy_shadow_project() {
   local entry name
   while IFS= read -r -d '' entry; do

package/lib/__templates__/native-static/.coze

@@ -5,10 +5,10 @@ project_type = "web"
 
 [dev]
 build = []
-run = ["python3", "-m", "http.server", "${DEPLOY_RUN_PORT}", "--bind", "0.0.0.0"]
+run = [ "sh", "-c", "exec python3 -m http.server ${DEPLOY_RUN_PORT} --bind 0.0.0.0" ]
 run_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/serve.ps1"]
 
 [deploy]
 build = []
-run = ["python3", "-m", "http.server", "${DEPLOY_RUN_PORT}", "--bind", "0.0.0.0"]
+run = [ "sh", "-c", "exec python3 -m http.server ${DEPLOY_RUN_PORT} --bind 0.0.0.0" ]
 run_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/serve.ps1"]

package/lib/__templates__/nextjs/.coze

@@ -9,7 +9,7 @@ run = ["bash", "./scripts/dev.sh"]
 run_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/dev.ps1"]
 validate = ["bash", "./scripts/validate.sh"]
 validate_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/validate.ps1"]
-deps = ["git"] # -> apt install git
+deps = ["git", "rsync"] # -> apt install git rsync
 
 [deploy]
 build = ["bash","./scripts/build.sh"]

package/lib/__templates__/nextjs/README.md

@@ -361,3 +361,21 @@ export const useStore = create<Store>((set) => ({
 3. **遵循 Next.js App Router 规范**，正确区分服务端/客户端组件
 4. **使用 TypeScript** 进行类型安全开发
 5. **使用 `@/` 路径别名** 导入模块（已配置）
+
+## 云盘源码与本地开发
+
+Vite、Next.js、Nuxt 的 Unix 开发脚本在 `COZE_DRIVE_ROOT`（默认 `/Coze/Drive`）内通过
+`scripts/local-workspace.cjs` 将源码用 `rsync` 同步到本机临时目录。系统需提供 Node.js、pnpm、bash 和 rsync。
+所有开发与修复仍在云盘源码目录完成，从该目录执行 `.coze` 的 `[dev]` 命令。
+
+- `prepare.sh` 同步并在本地安装依赖；安装成功且云盘依赖输入未变化时，仅将更新的锁文件回写云盘。
+- `dev.sh` 在本地镜像运行开发服务，每轮 rsync 结束后等待一秒再同步，框架监听本地文件进行热更新。
+  同步失败或依赖输入变化时停止服务；修复后重新运行 `prepare.sh` / `dev.sh`。
+- `validate.sh` 使用独立的本地 `check` 目录，避免类型生成影响正在运行的 `dev` 服务。
+- 同步排除 `.git`、`node_modules`、日志和框架输出；不要在镜像修复源码或将依赖、编译产物回传云盘。
+  日志和 PID 默认保留在源码目录的 `logs/`，实际镜像路径见脚本输出。
+
+本地镜像仅用于 `[dev].build/run/validate`。部署配置、`build.sh`、`start.sh` 保持原流程；
+普通本地目录和 Windows PowerShell 入口也保持原流程。
+存量项目通过新版 CLI 的 `coze-dev patch --dry-run` / `coze-dev patch` 升级，沿用 patch 总开关。
+仅升级完整匹配旧模板的三个 Unix 开发脚本并保留端口；自定义开发脚本、命令或同名 helper 会跳过。

package/lib/__templates__/nextjs/eslint.config.mjs

@@ -52,7 +52,7 @@ const eslintConfig = defineConfig([
     'server.js',
     'dist/',
     // Script files (CommonJS):
-    'scripts/**/*.js',
+    'scripts/**/*.{js,cjs}',
   ]),
 ]);
 

package/lib/__templates__/nextjs/next.config.ts

@@ -1,18 +1,9 @@
 import type { NextConfig } from 'next';
-import path from 'path';
 
 const nextConfig: NextConfig = {
   // outputFileTracingRoot: path.resolve(__dirname, '../../'),  // Uncomment and add 'import path from "path"' if needed
   /* config options here */
   serverExternalPackages: ['coze-coding-dev-sdk'],
-  webpack: (config, { dev }) => {
-    if (dev && config.cache && config.cache.type === 'filesystem') {
-      config.cache.cacheDirectory = path.resolve(
-        'node_modules/.cache/next-webpack',
-      );
-    }
-    return config;
-  },
   allowedDevOrigins: ['*.dev.coze.site'],
   images: {
     remotePatterns: [

package/lib/__templates__/nextjs/scripts/build.ps1

@@ -8,7 +8,7 @@ Write-Host "Installing dependencies..."
 if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 
 Write-Host "Building the Next.js project..."
-& pnpm next build --webpack
+& pnpm next build
 if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
 
 Write-Host "Bundling server with tsup..."

package/lib/__templates__/nextjs/scripts/build.sh

@@ -6,10 +6,10 @@ COZE_WORKSPACE_PATH="${COZE_WORKSPACE_PATH:-$(pwd)}"
 cd "${COZE_WORKSPACE_PATH}"
 
 echo "Installing dependencies..."
-bash "$COZE_WORKSPACE_PATH/scripts/prepare-node-modules.sh" --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
+pnpm install --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
 
 echo "Building the Next.js project..."
-pnpm next build --webpack
+pnpm next build
 
 echo "Bundling server with tsup..."
 pnpm tsup src/server.ts --format cjs --platform node --target node20 --outDir dist --no-splitting --no-minify

package/lib/__templates__/nextjs/scripts/dev.ps1

@@ -28,7 +28,7 @@ Stop-ListeningProcess $port
 
 <% if (process.env.NODE_ENV === 'test') { %>
 $env:PORT = "$port"
-& pnpm next dev --webpack --hostname 0.0.0.0 --port $port
+& pnpm next dev --hostname 0.0.0.0 --port $port
 exit $LASTEXITCODE
 <% } else { %>
 $logDirectory = if ($env:COZE_LOG_DIR) { $env:COZE_LOG_DIR } else { Join-Path $workspace "logs" }
@@ -45,7 +45,7 @@ if (Test-Path $pidFile) {
 $previousPort = $env:PORT
 $env:PORT = "$port"
 try {
-  $process = Start-Process -FilePath $env:ComSpec -ArgumentList @("/d", "/s", "/c", "pnpm next dev --webpack --hostname 0.0.0.0 --port $port") -WorkingDirectory $workspace -RedirectStandardOutput $logFile -RedirectStandardError $errorLogFile -PassThru
+  $process = Start-Process -FilePath $env:ComSpec -ArgumentList @("/d", "/s", "/c", "pnpm next dev --hostname 0.0.0.0 --port $port") -WorkingDirectory $workspace -RedirectStandardOutput $logFile -RedirectStandardError $errorLogFile -PassThru
 } finally {
   if ($null -eq $previousPort) { Remove-Item Env:PORT -ErrorAction SilentlyContinue } else { $env:PORT = $previousPort }
 }

package/lib/__templates__/nextjs/scripts/dev.sh

@@ -1,14 +1,20 @@
 #!/bin/bash
 set -Eeuo pipefail
 
+# Resolve the source project from this script, then let the Web runner choose its local mirror.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd -P)"
+if [[ "${COZE_WEB_LOCAL_ACTIVE:-}" != "${PROJECT_ROOT}" ]]; then
+  exec node "${SCRIPT_DIR}/local-workspace.cjs" dev "$@"
+fi
+COZE_WORKSPACE_PATH="${PROJECT_ROOT}"
+
 <% if (process.env.NODE_ENV === 'test') { %>
 # 测试环境：支持环境变量覆盖端口
 PORT="${PORT:-<%= port %>}"
-COZE_WORKSPACE_PATH="${COZE_WORKSPACE_PATH:-$(pwd)}"
 DEPLOY_RUN_PORT="${DEPLOY_RUN_PORT:-${PORT}}"
 <% } else { %>
 PORT="${DEPLOY_RUN_PORT:-${PORT:-<%= port %>}}"
-COZE_WORKSPACE_PATH="${COZE_WORKSPACE_PATH:-$(pwd)}"
 DEPLOY_RUN_PORT="${DEPLOY_RUN_PORT:-${PORT}}"
 <% } %>
 
@@ -52,68 +58,17 @@ kill_port_if_listening() {
     echo "Port ${DEPLOY_RUN_PORT} cleared."
 }
 
-# Next 的路由清单由 watchpack 每次启动重新扫 src 下的 app/pages 目录现算，而 watchpack
-# 不会进入软链目录，软链子树里的 page/route 会被静默跳过：既不注册路由，也不打任何日志，
-# 表现为该路由一直 404 而 .next 里没有它的产物。这里只做提示，不改动源码。
-warn_source_symlinks() {
-    local source_dir="${COZE_WORKSPACE_PATH}/src"
-    local links link
-    if [[ ! -e "${source_dir}" ]]; then
-      return
-    fi
-    links=$(find "${source_dir}" -type l 2>/dev/null || true)
-    if [[ -z "${links}" ]]; then
-      return
-    fi
-    echo "Warning: 以下路径是软链，Next 不会进入其中，里面的 page/route 不会被编译：" >&2
-    while IFS= read -r link; do
-      echo "  ${link}" >&2
-    done <<< "${links}"
-}
-
-# 云盘挂载偶尔会把新建文件的 mtime 设为 Unix epoch，这种时间戳会让所有按 mtime 判断新旧的
-# 环节（Next 的首轮路由扫描、webpack 的 timestamp 快照、tsbuildinfo）拿到错误的结论。
-# 只修 mtime 确实异常的那些条目：无条件刷新整棵 app/pages 会让 webpack 每次启动都重算全部
-# 路由文件的 hash，并让云盘把它们全部重传一遍。不跟随软链、不改文件内容。
-# 判定 mtime 是否异常的下界。真实的项目文件不可能早于这个时间，落在它之前的只有被云盘写坏的
-# 时间戳，所以用它把"需要修"和"本来就好"区分开。
-DRIVE_MTIME_FLOOR="1971-01-01"
-
-refresh_drive_route_mtimes() {
-    local drive_root="${COZE_DRIVE_ROOT:-/Coze/Drive}"
-    local project_root route_dir
-    project_root="$(pwd -P)"
-    if [[ -d "${drive_root}" ]]; then
-      drive_root="$(cd "${drive_root}" && pwd -P)"
-    else
-      drive_root="${drive_root%/}"
-    fi
-
-    case "${project_root}" in
-      "${drive_root}"|"${drive_root}"/*) ;;
-      *) return ;;
-    esac
-
-    for route_dir in "${COZE_WORKSPACE_PATH}/src/app" "${COZE_WORKSPACE_PATH}/src/pages"; do
-      [[ -d "${route_dir}" ]] || continue
-      if ! find -P "${route_dir}" \( -type f -o -type d \) ! -newermt "${DRIVE_MTIME_FLOOR}" -exec touch {} + 2>/dev/null; then
-        echo "Warning: failed to refresh Next route timestamps in ${route_dir}." >&2
-      fi
-    done
-}
-
 <% if (process.env.NODE_ENV === 'test') { %>
 echo "Clearing port ${DEPLOY_RUN_PORT} before start."
 kill_port_if_listening
-COZE_REUSE_NODE_MODULES=1 bash "${COZE_WORKSPACE_PATH}/scripts/prepare-node-modules.sh" --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
-bash "${COZE_WORKSPACE_PATH}/scripts/prepare-next-dev-output.sh"
-warn_source_symlinks
-refresh_drive_route_mtimes
+if [[ "${COZE_WEB_LOCAL_MIRROR:-}" != "1" ]]; then
+  pnpm install --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
+fi
 echo "Starting HTTP service on port ${DEPLOY_RUN_PORT} for dev..."
 
 # 测试环境保持服务为前台进程，便于 e2e 收集输出并停止进程。
 # 开发环境直接使用 Next 的 dev CLI，避免云盘文件事件在 custom server 链路中丢失。
-exec pnpm next dev --webpack --hostname 0.0.0.0 --port "${DEPLOY_RUN_PORT}"
+exec node "${SCRIPT_DIR}/local-workspace.cjs" watch pnpm next dev --hostname 0.0.0.0 --port "${DEPLOY_RUN_PORT}"
 <% } else { %>
 LOG_DIR="${COZE_LOG_DIR:-${COZE_WORKSPACE_PATH}/logs}"
 LOG_FILE="${LOG_DIR}/app.log"
@@ -300,10 +255,9 @@ fi
 
 echo "Clearing port ${DEPLOY_RUN_PORT} before start."
 kill_port_if_listening
-COZE_REUSE_NODE_MODULES=1 bash "${COZE_WORKSPACE_PATH}/scripts/prepare-node-modules.sh" --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
-bash "${COZE_WORKSPACE_PATH}/scripts/prepare-next-dev-output.sh"
-warn_source_symlinks
-refresh_drive_route_mtimes
+if [[ "${COZE_WEB_LOCAL_MIRROR:-}" != "1" ]]; then
+  pnpm install --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
+fi
 echo "Starting HTTP service on port ${DEPLOY_RUN_PORT} for dev..."
 
 mkdir -p "${LOG_DIR}"
@@ -311,7 +265,7 @@ mkdir -p "${LOG_DIR}"
 
 export PORT="${DEPLOY_RUN_PORT}"
 server_pid="$(spawn_detached "${COZE_WORKSPACE_PATH}" "${LOG_FILE}" \
-  "$(command -v pnpm)" next dev --webpack --hostname 0.0.0.0 --port "${DEPLOY_RUN_PORT}")"
+  "$(command -v node)" "${SCRIPT_DIR}/local-workspace.cjs" watch "$(command -v pnpm)" next dev --hostname 0.0.0.0 --port "${DEPLOY_RUN_PORT}")"
 if [[ -z "${server_pid}" ]]; then
   echo "Dev server failed to start: 未获取到后台进程 PID。" >&2
   dump_log

package/lib/__templates__/nextjs/scripts/local-workspace.cjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+// Web source is owned by Drive. Only these wrappers may write to the local mirror.
+/* eslint-disable @typescript-eslint/no-require-imports -- Standalone CommonJS runtime shipped without CLI dependencies. */
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { createHash } = require('node:crypto');
+const { spawn, execFileSync } = require('node:child_process');
+const { setTimeout: delay } = require('node:timers/promises');
+
+const scriptRoot = fs.realpathSync(path.resolve(__dirname, '..'));
+const source = fs.realpathSync(
+  process.env.COZE_WEB_LOCAL_ACTIVE === scriptRoot && process.env.COZE_WEB_SOURCE_PATH
+    ? process.env.COZE_WEB_SOURCE_PATH : scriptRoot,
+);
+const drivePath = path.resolve(process.env.COZE_DRIVE_ROOT || '/Coze/Drive');
+const drive = fs.existsSync(drivePath) ? fs.realpathSync(drivePath) : drivePath;
+const inside = (root, candidate) => candidate === root || candidate.startsWith(`${root}${path.sep}`);
+const onDrive = inside(drive, source);
+const digest = value => createHash('sha256').update(value).digest('hex');
+// Separate from /tmp/nm: older dependency helpers clean unknown entries there.
+const cacheRoot = path.join(os.tmpdir(), `coze-web-${process.getuid()}`);
+const projectCache = path.join(cacheRoot, digest(source));
+const exclusions = [
+  'node_modules', '.git', '/logs', '.pnpm-store', '.next', '.nuxt', '.output',
+  '/dist', '/dist-server', '.cache', '.turbo', '*.tsbuildinfo',
+  '.eslintcache', '.stylelintcache', '/next-env.d.ts', '/tsconfig.json',
+];
+const installArgs = ['install', '--prefer-frozen-lockfile', '--prefer-offline'];
+let interrupted = false;
+const children = new Set();
+
+function stopTree(child) {
+  if (!child.pid || child.exitCode !== null) return;
+  // Keep descendants in the detached launcher's group so readiness ownership works.
+  // Also stop grandchildren when the test/foreground path is signalled directly.
+  let rows = [];
+  try {
+    rows = execFileSync('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf8' })
+      .trim().split('\n').map(line => line.trim().split(/\s+/).map(Number));
+  } catch { /* The launcher still owns and reaps its process group. */ }
+  const pids = [child.pid];
+  for (let i = 0; i < pids.length; i++) {
+    for (const [pid, parent] of rows) if (parent === pids[i]) pids.push(pid);
+  }
+  for (const pid of pids.reverse()) {
+    try { process.kill(pid, 'SIGTERM'); } catch { /* Already exited. */ }
+  }
+  const timer = setTimeout(() => {
+    for (const pid of pids) {
+      try { process.kill(pid, 'SIGKILL'); } catch { /* Already exited. */ }
+    }
+  }, 2000);
+  timer.unref();
+}
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    interrupted = true;
+    process.exitCode = signal === 'SIGINT' ? 130 : 143;
+    for (const child of children) stopTree(child);
+  });
+}
+
+function run(command, args, cwd, env = process.env) {
+  if (interrupted) return Promise.reject(new Error('Interrupted'));
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, env, stdio: 'inherit' });
+    children.add(child);
+    child.once('error', error => { children.delete(child); reject(error); });
+    child.once('exit', (code, signal) => {
+      children.delete(child);
+      if (code === 0) resolve();
+      else reject(new Error(`${command} exited with ${signal || code}`));
+    });
+  });
+}
+
+function ensureCache() {
+  for (const dir of [cacheRoot, projectCache]) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (fs.lstatSync(dir).isSymbolicLink() || fs.statSync(dir).uid !== process.getuid()) {
+      throw new Error(`Refusing unmanaged workspace directory: ${dir}`);
+    }
+    if (inside(drive, fs.realpathSync(dir))) {
+      throw new Error(`Local workspace must be outside Coze Drive: ${dir}`);
+    }
+  }
+}
+
+async function locked(action, name = 'sync') {
+  const lock = path.join(projectCache, `${name}.lock`);
+  const started = Date.now();
+  let missingOwner = 0;
+  while (true) {
+    if (interrupted) throw new Error('Interrupted');
+    try { fs.mkdirSync(lock); break; } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+    }
+    let alive = false;
+    try {
+      const pid = Number(fs.readFileSync(path.join(lock, 'pid'), 'utf8'));
+      if (Number.isInteger(pid) && pid > 0) { process.kill(pid, 0); alive = true; }
+    } catch (error) { if (error.code === 'EPERM') alive = true; }
+    missingOwner = alive ? 0 : missingOwner + 1;
+    if (missingOwner >= 2) {
+      const stale = `${lock}.stale-${process.pid}`;
+      try {
+        fs.renameSync(lock, stale);
+        fs.rmSync(stale, { recursive: true });
+      } catch (error) { if (error.code !== 'ENOENT') throw error; }
+      missingOwner = 0;
+      continue;
+    }
+    if (Date.now() - started > 120000) throw new Error(`Timed out waiting for ${lock}`);
+    await delay(500);
+  }
+  fs.writeFileSync(path.join(lock, 'pid'), String(process.pid));
+  try { return await action(); }
+  finally { fs.rmSync(lock, { recursive: true, force: true }); }
+}
+
+async function sync(local) {
+  if (!fs.existsSync(path.join(source, 'package.json'))) {
+    throw new Error(`Source project is unavailable: ${source}`);
+  }
+  fs.mkdirSync(local, { recursive: true });
+  if (fs.realpathSync(local) !== local) throw new Error(`Refusing workspace symlink: ${local}`);
+  // Checksums catch same-size edits with unchanged/epoch Drive mtimes. Do not use -t:
+  // changed local files get fresh mtimes and unchanged files retain watcher snapshots.
+  // Materialize source links so the framework never follows them back onto Drive.
+  await run('rsync', [
+    '-rLp', '--checksum', '--delete', '--delay-updates',
+    ...exclusions.map(entry => `--exclude=${entry}`), `${source}/`, `${local}/`,
+  ], source);
+  // Next rewrites these inputs (dev/types vs types and tsconfig defaults). Preserve
+  // generated local changes until their canonical source content actually changes.
+  for (const file of ['next-env.d.ts', 'tsconfig.json']) {
+    const input = path.join(source, file);
+    const output = path.join(local, file);
+    const state = path.join(projectCache, `${path.basename(local)}.${file}.source`);
+    const fingerprint = fs.existsSync(input) ? digest(fs.readFileSync(input)) : 'missing';
+    if (readOptional(state).toString() !== fingerprint || !fs.existsSync(output)) {
+      if (fingerprint !== 'missing') fs.copyFileSync(input, output);
+      else fs.rmSync(output, { force: true });
+      fs.writeFileSync(state, fingerprint);
+    }
+  }
+}
+
+function readOptional(file) {
+  try { return fs.readFileSync(file); }
+  catch (error) { if (error.code === 'ENOENT') return Buffer.alloc(0); throw error; }
+}
+
+function installInput(root) {
+  const hash = createHash('sha256');
+  const visit = (dir, all = false) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (['node_modules', '.git', 'logs', '.pnpm-store', '.next', '.nuxt', '.output', 'dist', 'dist-server', '.cache', '.turbo'].includes(entry.name)) continue;
+      const file = path.join(dir, entry.name);
+      // Follow source links just as rsync -L does, while detecting loops explicitly.
+      const real = fs.realpathSync(file);
+      if (entry.isDirectory() || (entry.isSymbolicLink() && fs.statSync(file).isDirectory())) {
+        if (ancestors.has(real)) throw new Error(`Source symlink cycle: ${file}`);
+        ancestors.add(real);
+        visit(file, all || entry.name === 'patches');
+        ancestors.delete(real);
+      }
+      else if (all || ['package.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml', '.npmrc', '.pnpmfile.cjs', '.pnpmfile.js'].includes(entry.name)) {
+        hash.update(path.relative(root, file)).update('\0').update(readOptional(file)).update('\0');
+      }
+    }
+  };
+  const ancestors = new Set([fs.realpathSync(root)]);
+  visit(root);
+  return hash.digest('hex');
+}
+
+function localEnv(local) {
+  return {
+    ...process.env,
+    COZE_WEB_LOCAL_ACTIVE: local,
+    COZE_WEB_SOURCE_PATH: source,
+    COZE_WEB_LOCAL_MIRROR: onDrive ? '1' : '',
+    COZE_WORKSPACE_PATH: local,
+    // Keep the existing discoverable log/PID location in the source project.
+    COZE_LOG_DIR: process.env.COZE_LOG_DIR || path.join(source, 'logs'),
+    PWD: local,
+    INIT_CWD: local,
+    ...(onDrive ? { npm_config_store_dir: path.join(cacheRoot, 'store') } : {}),
+  };
+}
+
+async function install(local, mode) {
+  const state = path.join(projectCache, `${mode}.install`);
+  const version = execFileSync('pnpm', ['--version'], { encoding: 'utf8' }).trim();
+  const fingerprint = () => digest([
+    installInput(local), version, process.version, process.env.NODE_ENV,
+    process.env.npm_config_production, process.env.NPM_CONFIG_PRODUCTION,
+    process.env.PNPM_CONFIG_PRODUCTION,
+  ].join('\n'));
+  // Lifecycle scripts may generate files from arbitrary source, so do not reuse
+  // their install based on dependency metadata alone. Read manifests as text here
+  // (no executable hooks or private CLI dependencies in the standalone helper).
+  const manifest = readOptional(path.join(local, 'package.json')).toString();
+  const hasLifecycle = /"(?:install|postinstall|prepare)"\s*:/.test(manifest);
+  // Workspace and local file dependencies can run lifecycles outside the root.
+  // Let pnpm validate those installs instead of assuming the root marker is enough.
+  const hasLocalDependencies = fs.existsSync(path.join(local, 'pnpm-workspace.yaml')) ||
+    /"(?:workspace|file|link):/.test(manifest);
+  const hasHooks = ['.pnpmfile.cjs', '.pnpmfile.js'].some(file => fs.existsSync(path.join(local, file))) ||
+    /^\s*pnpmfile\s*=/m.test(readOptional(path.join(local, '.npmrc')).toString());
+  if (!hasLifecycle && !hasHooks && !hasLocalDependencies && readOptional(state).toString() === fingerprint() &&
+      fs.existsSync(path.join(local, 'node_modules', '.modules.yaml'))) return;
+  fs.rmSync(state, { force: true });
+  const before = installInput(source);
+  if (before !== installInput(local)) {
+    throw new Error('Dependency inputs changed during sync; rerun prepare.sh.');
+  }
+  await run('pnpm', [...installArgs, '--store-dir', path.join(cacheRoot, 'store')], local, localEnv(local));
+  if (before !== installInput(source)) {
+    throw new Error('Dependency inputs changed on Drive during installation; rerun prepare.sh. Lockfile was not overwritten.');
+  }
+  const lockfile = path.join(local, 'pnpm-lock.yaml');
+  if (fs.existsSync(lockfile) && !readOptional(lockfile).equals(readOptional(path.join(source, 'pnpm-lock.yaml')))) {
+    const temporary = path.join(source, `.pnpm-lock.yaml.${process.pid}.tmp`);
+    try {
+      fs.copyFileSync(lockfile, temporary);
+      fs.renameSync(temporary, path.join(source, 'pnpm-lock.yaml'));
+    } finally { fs.rmSync(temporary, { force: true }); }
+  }
+  fs.writeFileSync(state, fingerprint());
+}
+
+async function watch(args) {
+  const local = fs.realpathSync(process.env.COZE_WEB_LOCAL_ACTIVE || path.resolve(__dirname, '..'));
+  if (!onDrive) return run(args[0], args.slice(1), local);
+  ensureCache();
+  if (local !== path.join(fs.realpathSync(projectCache), 'dev')) {
+    throw new Error(`Refusing to watch an unmanaged workspace: ${local}`);
+  }
+  const preparedInput = installInput(local);
+  let running = true;
+  let syncError;
+  const command = run(args[0], args.slice(1), local).finally(() => { running = false; });
+  const poll = (async () => {
+    while (running && !interrupted) {
+      await delay(1000);
+      if (!running || interrupted) break;
+      try {
+        await locked(async () => {
+          await sync(local);
+          if (installInput(local) !== preparedInput) {
+            throw new Error('Dependency inputs changed; rerun prepare.sh and dev.sh before previewing.');
+          }
+        });
+      }
+      catch (error) {
+        syncError = error;
+        for (const child of children) stopTree(child);
+        break;
+      }
+    }
+  })();
+  const results = await Promise.allSettled([command, poll]);
+  if (syncError) throw syncError;
+  if (results[0].status === 'rejected') throw results[0].reason;
+}
+
+async function main() {
+  const [action, ...args] = process.argv.slice(2);
+  if (action === 'watch') return watch(args);
+  if (!['prepare', 'dev', 'validate'].includes(action)) throw new Error(`Unknown Web action: ${action}`);
+  if (!onDrive) {
+    return run('bash', [path.join(source, 'scripts', `${action}.sh`), ...args], source, localEnv(source));
+  }
+  ensureCache();
+  const mode = action === 'validate' ? 'check' : 'dev';
+  const local = path.join(fs.realpathSync(projectCache), mode);
+  console.log(`[web] Source: ${source}\n[web] Local ${mode} workspace: ${local}`);
+  if (action === 'validate') {
+    return locked(async () => {
+      await locked(async () => {
+        await sync(local);
+        await install(local, mode);
+      });
+      await run('bash', [path.join(local, 'scripts', 'validate.sh'), ...args], local, localEnv(local));
+    }, 'check');
+  } else {
+    await locked(async () => {
+      await sync(local);
+      await install(local, mode);
+    });
+  }
+  await run('bash', [path.join(local, 'scripts', `${action}.sh`), ...args], local, localEnv(local));
+}
+
+main().catch(error => {
+  console.error(`[web] ${error.message}`);
+  process.exitCode = process.exitCode || 1;
+});

package/lib/__templates__/nextjs/scripts/prepare.sh

@@ -1,9 +1,17 @@
 #!/bin/bash
 set -Eeuo pipefail
 
-COZE_WORKSPACE_PATH="${COZE_WORKSPACE_PATH:-$(pwd)}"
+# Resolve the source project from this script, then let the Web runner choose its local mirror.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd -P)"
+if [[ "${COZE_WEB_LOCAL_ACTIVE:-}" != "${PROJECT_ROOT}" ]]; then
+  exec node "${SCRIPT_DIR}/local-workspace.cjs" prepare "$@"
+fi
+COZE_WORKSPACE_PATH="${PROJECT_ROOT}"
 
 cd "${COZE_WORKSPACE_PATH}"
 
 echo "Installing dependencies..."
-bash "$COZE_WORKSPACE_PATH/scripts/prepare-node-modules.sh" --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
+if [[ "${COZE_WEB_LOCAL_MIRROR:-}" != "1" ]]; then
+  pnpm install --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
+fi

package/lib/__templates__/nextjs/scripts/validate.sh

@@ -1,10 +1,20 @@
 #!/bin/bash
 set -Eeuo pipefail
 
-COZE_WORKSPACE_PATH="${COZE_WORKSPACE_PATH:-$(pwd)}"
+# Resolve the source project from this script, then let the Web runner choose its local mirror.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd -P)"
+if [[ "${COZE_WEB_LOCAL_ACTIVE:-}" != "${PROJECT_ROOT}" ]]; then
+  exec node "${SCRIPT_DIR}/local-workspace.cjs" validate "$@"
+fi
+COZE_WORKSPACE_PATH="${PROJECT_ROOT}"
 
 cd "${COZE_WORKSPACE_PATH}"
 
+if [[ "${COZE_WEB_LOCAL_MIRROR:-}" == "1" ]]; then
+  pnpm next typegen
+fi
+
 echo "🔍 Running validate..."
 pnpm validate
 echo "✅ Validate passed!"

package/lib/__templates__/nextjs/src/server.ts

@@ -7,7 +7,7 @@ const hostname = process.env.HOSTNAME || 'localhost';
 const port = parseInt(process.env.PORT || '<%= port %>', 10);
 
 // Create Next.js app
-const app = next({ dev, hostname, port, webpack: true });
+const app = next({ dev, hostname, port });
 const handle = app.getRequestHandler();
 
 app.prepare().then(() => {