@coze-arch/cli 0.1.5 → 0.1.8-alpha.2ee669

package/lib/__templates__/nuxt-vue/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__/nuxt-vue/scripts/prepare-node-modules.sh

@@ -0,0 +1,380 @@
+#!/usr/bin/env bash
+# Install dependencies on local disk and expose them to the source tree by symlink.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+if [ "$(basename "$(dirname "$SCRIPT_DIR")")" = ".cozeproj" ]; then
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd -P)"
+else
+  PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+fi
+
+command -v pnpm >/dev/null 2>&1 || {
+  echo "[node_modules] pnpm is required" >&2
+  exit 1
+}
+
+DRIVE_ROOT="${COZE_DRIVE_ROOT:-/Coze/Drive}"
+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"/*) ;;
+  *)
+    (cd "$PROJECT_ROOT" && pnpm install "$@")
+    exit 0
+    ;;
+esac
+
+NM_ROOT="/tmp/nm"
+PROJECT_ID="$(basename "$PROJECT_ROOT")-$(printf '%s' "$PROJECT_ROOT" | cksum | awk '{print $1}')"
+mkdir -p "$NM_ROOT"
+WORK_DIR="$NM_ROOT/$PROJECT_ID"
+case "$WORK_DIR" in
+  "$DRIVE_ROOT"|"$DRIVE_ROOT"/*)
+    echo "[node_modules] local dependency directory must not be on Coze Drive: $WORK_DIR" >&2
+    exit 1
+    ;;
+esac
+
+LOCK_DIR="$NM_ROOT/$PROJECT_ID.lock"
+LOCK_TIMEOUT_SECONDS="${COZE_NODE_MODULES_LOCK_TIMEOUT_SECONDS:-120}"
+case "$LOCK_TIMEOUT_SECONDS" in
+  ''|*[!0-9]*|0)
+    echo "[node_modules] COZE_NODE_MODULES_LOCK_TIMEOUT_SECONDS must be a positive integer" >&2
+    exit 1
+    ;;
+esac
+
+lock_owner_is_alive() {
+  local owner_pid=""
+  [ -f "$LOCK_DIR/pid" ] || return 1
+  IFS= read -r owner_pid < "$LOCK_DIR/pid" || return 1
+  case "$owner_pid" in
+    ''|*[!0-9]*) return 1 ;;
+  esac
+  kill -0 "$owner_pid" 2>/dev/null
+}
+
+release_lock() {
+  local owner_pid=""
+  [ -f "$LOCK_DIR/pid" ] || return 0
+  IFS= read -r owner_pid < "$LOCK_DIR/pid" || true
+  if [ "$owner_pid" = "$$" ]; then
+    rm -f "$LOCK_DIR/pid"
+    rmdir "$LOCK_DIR" 2>/dev/null || true
+  fi
+}
+
+lock_started_at="$(date +%s)"
+missing_owner_checks=0
+while ! mkdir "$LOCK_DIR" 2>/dev/null; do
+  if lock_owner_is_alive; then
+    missing_owner_checks=0
+  else
+    missing_owner_checks=$((missing_owner_checks + 1))
+    if [ "$missing_owner_checks" -ge 2 ]; then
+      stale_lock_dir="$LOCK_DIR.stale.$$"
+      if mv "$LOCK_DIR" "$stale_lock_dir" 2>/dev/null; then
+        echo "[node_modules] Recovering stale dependency preparation lock."
+        rm -rf "$stale_lock_dir"
+      fi
+      missing_owner_checks=0
+      continue
+    fi
+  fi
+
+  lock_now="$(date +%s)"
+  if [ $((lock_now - lock_started_at)) -ge "$LOCK_TIMEOUT_SECONDS" ]; then
+    echo "[node_modules] Timed out waiting ${LOCK_TIMEOUT_SECONDS}s for dependency preparation lock: $LOCK_DIR" >&2
+    exit 1
+  fi
+  echo "[node_modules] Waiting for another dependency preparation for this project..."
+  sleep 1
+done
+printf '%s\n' "$$" > "$LOCK_DIR/pid"
+trap release_lock EXIT
+
+mkdir -p "$WORK_DIR"
+INSTALL_STATE_FILE="$WORK_DIR/.install-state"
+
+# Previous versions mirrored the whole project into WORK_DIR. That gives pnpm
+# and framework dev servers two paths for the same source tree, which breaks
+# file watching and on-demand compilation. Keep only managed local outputs.
+cleanup_legacy_workspace() {
+  local workspace_dir="$1" entry name
+  if [ -L "$workspace_dir" ] || { [ -e "$workspace_dir" ] && [ ! -d "$workspace_dir" ]; }; then
+    rm -rf "$workspace_dir"
+    return
+  fi
+  if [ ! -d "$workspace_dir" ]; then
+    return 0
+  fi
+
+  while IFS= read -r -d '' entry; do
+    name="$(basename "$entry")"
+    [ "$name" = "node_modules" ] || rm -rf "$entry"
+  done < <(find "$workspace_dir" -mindepth 1 -maxdepth 1 -print0)
+}
+
+# Preserve existing project caches during dependency preparation.
+cleanup_legacy_shadow_project() {
+  local entry name
+  while IFS= read -r -d '' entry; do
+    name="$(basename "$entry")"
+    case "$name" in
+      node_modules|client|server|caches|.install-state) continue ;;
+    esac
+    rm -rf "$entry"
+  done < <(find "$WORK_DIR" -mindepth 1 -maxdepth 1 -print0)
+
+  for workspace in client server; do
+    cleanup_legacy_workspace "$WORK_DIR/$workspace"
+  done
+}
+
+link_install_entry() {
+  local source_path="$1" target_path="$2"
+  rm -rf "$target_path"
+  if [ -e "$source_path" ]; then
+    ln -s "$source_path" "$target_path"
+  fi
+}
+
+hash_install_input() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum | awk '{print $1}'
+  elif command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 | awk '{print $1}'
+  else
+    cksum | awk '{print $1 "-" $2}'
+  fi
+}
+
+append_file_to_install_fingerprint() {
+  local relative_path="$1"
+  local source_path="$PROJECT_ROOT/$relative_path"
+  printf 'path=%s\n' "$relative_path"
+  if [ -f "$source_path" ]; then
+    cat "$source_path"
+  else
+    printf '<missing>\n'
+  fi
+}
+
+append_directory_to_install_fingerprint() {
+  local relative_path="$1"
+  local source_path="$PROJECT_ROOT/$relative_path"
+  local file
+  printf 'path=%s\n' "$relative_path"
+  if [ ! -d "$source_path" ]; then
+    printf '<missing>\n'
+    return
+  fi
+
+  while IFS= read -r file; do
+    printf 'file=%s\n' "${file#"${PROJECT_ROOT}/"}"
+    cat "$file"
+  done < <(find -P "$source_path" -type f -print | LC_ALL=C sort)
+}
+
+# Everything that can change the resolved dependency tree. The leading version marker
+# invalidates every stored state when this scheme itself changes.
+calculate_install_fingerprint() {
+  local filename workspace argument
+  {
+    printf 'prepare-node-modules-install-state=1\n'
+    printf 'node-version=%s\n' "$(node --version)"
+    printf 'pnpm-version=%s\n' "$(pnpm --version)"
+    printf 'node-env=%s\n' "${NODE_ENV:-}"
+    printf 'npm-config-production=%s\n' "${npm_config_production:-}"
+    printf 'npm-config-production-upper=%s\n' "${NPM_CONFIG_PRODUCTION:-}"
+    printf 'pnpm-config-production=%s\n' "${PNPM_CONFIG_PRODUCTION:-}"
+    for argument in "$@"; do
+      printf 'install-argument=%s\n' "$argument"
+    done
+    for filename in package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc; do
+      append_file_to_install_fingerprint "$filename"
+    done
+    for workspace in client server; do
+      append_file_to_install_fingerprint "$workspace/package.json"
+    done
+    append_directory_to_install_fingerprint patches
+  } | hash_install_input
+}
+
+install_requires_refresh() {
+  local argument
+  for argument in "$@"; do
+    case "$argument" in
+      --force|-f|--lockfile-only|--fix-lockfile) return 0 ;;
+    esac
+  done
+  return 1
+}
+
+# Reuse skips pnpm install entirely, so it must not skip side effects that live outside
+# node_modules. preinstall is exempt: it only guards which package manager may run, and
+# there is no install to guard when the tree is already in place.
+package_has_install_lifecycle() {
+  local package_path="$1"
+  node - "$package_path" <<'NODE'
+const fs = require('node:fs');
+const [packagePath] = process.argv.slice(2);
+
+try {
+  const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+  const scripts = packageJson && typeof packageJson.scripts === 'object' && packageJson.scripts
+    ? packageJson.scripts
+    : {};
+  const hasLifecycle = ['install', 'postinstall', 'prepare'].some(
+    name => typeof scripts[name] === 'string' && scripts[name].trim() !== '',
+  );
+
+  process.exit(hasLifecycle ? 0 : 1);
+} catch {
+  process.exit(0);
+}
+NODE
+}
+
+install_reuse_is_safe() {
+  local workspace package_path
+  for package_path in "$PROJECT_ROOT/.pnpmfile.cjs" "$PROJECT_ROOT/.pnpmfile.js"; do
+    if [ -e "$package_path" ]; then
+      echo "[node_modules] Reinstalling because pnpm hooks are present: $package_path"
+      return 1
+    fi
+  done
+
+  if [ -f "$PROJECT_ROOT/.npmrc" ] && grep -Eq '^[[:space:]]*pnpmfile[[:space:]]*=' "$PROJECT_ROOT/.npmrc"; then
+    echo "[node_modules] Reinstalling because .npmrc configures a pnpm hook."
+    return 1
+  fi
+
+  for workspace in . client server; do
+    package_path="$PROJECT_ROOT/$workspace/package.json"
+    [ -f "$package_path" ] || continue
+    if package_has_install_lifecycle "$package_path"; then
+      echo "[node_modules] Reinstalling because $package_path has an install lifecycle script."
+      return 1
+    fi
+  done
+  return 0
+}
+
+dependencies_are_ready() {
+  local workspace
+  [ -f "$WORK_DIR/node_modules/.modules.yaml" ] || return 1
+  for workspace in client server; do
+    if [ -f "$PROJECT_ROOT/$workspace/package.json" ] &&
+      [ ! -f "$WORK_DIR/$workspace/node_modules/.modules.yaml" ]; then
+      return 1
+    fi
+  done
+  return 0
+}
+
+# 判断顺序按代价从小到大排。指纹要读云盘上的 lockfile 和整个 patches/，所以放最后：只有其余
+# 条件都满足、确实可能复用时才付这份开销。build.sh 和 prepare.sh 不设开关，第一行就返回了。
+install_can_be_reused() {
+  local installed_fingerprint=""
+
+  [ "${COZE_REUSE_NODE_MODULES:-}" = "1" ] || return 1
+  install_requires_refresh "$@" && return 1
+  [ -f "$INSTALL_STATE_FILE" ] || return 1
+  IFS= read -r installed_fingerprint < "$INSTALL_STATE_FILE" || return 1
+  dependencies_are_ready || return 1
+  install_reuse_is_safe || return 1
+  [ "$installed_fingerprint" = "$(calculate_install_fingerprint "$@")" ] || return 1
+  return 0
+}
+
+write_install_state() {
+  local fingerprint="$1" temporary_state
+  temporary_state="$(mktemp "$WORK_DIR/.install-state.XXXXXX")"
+  printf '%s\n' "$fingerprint" > "$temporary_state"
+  mv -f "$temporary_state" "$INSTALL_STATE_FILE"
+}
+
+copy_install_metadata() {
+  local filename source_file target_file workspace
+  for filename in pnpm-lock.yaml pnpm-workspace.yaml .npmrc; do
+    source_file="$PROJECT_ROOT/$filename"
+    target_file="$WORK_DIR/$filename"
+    rm -f "$target_file"
+    if [ -f "$source_file" ]; then
+      cp "$source_file" "$target_file"
+    fi
+  done
+
+  link_install_entry "$PROJECT_ROOT/package.json" "$WORK_DIR/package.json"
+  link_install_entry "$PROJECT_ROOT/patches" "$WORK_DIR/patches"
+  link_install_entry "$PROJECT_ROOT/scripts" "$WORK_DIR/scripts"
+
+  for workspace in client server; do
+    if [ -f "$PROJECT_ROOT/$workspace/package.json" ]; then
+      mkdir -p "$WORK_DIR/$workspace"
+      link_install_entry "$PROJECT_ROOT/$workspace/package.json" "$WORK_DIR/$workspace/package.json"
+      link_install_entry "$PROJECT_ROOT/$workspace/scripts" "$WORK_DIR/$workspace/scripts"
+    else
+      rm -rf "$WORK_DIR/$workspace"
+    fi
+  done
+}
+
+link_node_modules() {
+  local source_dir="$1" target_dir="$2"
+  local current=""
+  mkdir -p "$target_dir"
+  if [ -L "$source_dir/node_modules" ]; then
+    current="$(readlink "$source_dir/node_modules")"
+    case "$current" in
+      "$NM_ROOT"/*/node_modules|"$NM_ROOT"/*/*/node_modules) ;;
+      *)
+        echo "[node_modules] refusing to replace unmanaged symlink: $source_dir/node_modules" >&2
+        exit 1
+        ;;
+    esac
+    rm "$source_dir/node_modules"
+  elif [ -e "$source_dir/node_modules" ]; then
+    rm -rf "$source_dir/node_modules"
+  fi
+  ln -s "$target_dir" "$source_dir/node_modules"
+}
+
+cleanup_legacy_shadow_project
+copy_install_metadata
+
+if install_can_be_reused "$@"; then
+  echo "[node_modules] Reusing unchanged dependencies in $WORK_DIR"
+else
+  # A stale state file must not survive a failed install.
+  rm -f "$INSTALL_STATE_FILE"
+  echo "[node_modules] Installing dependencies in $WORK_DIR"
+  if ! (cd "$WORK_DIR" && pnpm install "$@"); then
+    exit 1
+  fi
+
+  if [ -f "$WORK_DIR/pnpm-lock.yaml" ]; then
+    temporary_lockfile="$(mktemp "$PROJECT_ROOT/.pnpm-lock.yaml.XXXXXX")"
+    cp "$WORK_DIR/pnpm-lock.yaml" "$temporary_lockfile"
+    chmod 0644 "$temporary_lockfile"
+    mv -f "$temporary_lockfile" "$PROJECT_ROOT/pnpm-lock.yaml"
+  fi
+
+  # pnpm may have rewritten the lockfile, so record the fingerprint of the tree as it
+  # now stands. Otherwise the next run would see a changed input and reinstall.
+  write_install_state "$(calculate_install_fingerprint "$@")"
+fi
+
+link_node_modules "$PROJECT_ROOT" "$WORK_DIR/node_modules"
+for workspace in client server; do
+  if [ -f "$PROJECT_ROOT/$workspace/package.json" ]; then
+    link_node_modules "$PROJECT_ROOT/$workspace" "$WORK_DIR/$workspace/node_modules"
+  fi
+done
+
+echo "[node_modules] Dependencies ready"