@coze-arch/cli 0.0.36-alpha.b293fc → 0.0.36-alpha.e6ca88

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

@@ -0,0 +1,63 @@
+$ErrorActionPreference = "Stop"
+
+function Get-WorkspacePath {
+  if ($env:COZE_WORKSPACE_PATH) {
+    return $env:COZE_WORKSPACE_PATH
+  }
+  return (Get-Location).Path
+}
+
+function Stop-ProcessTree([int] $processId) {
+  if ($processId -gt 0 -and (Get-Process -Id $processId -ErrorAction SilentlyContinue)) {
+    & taskkill.exe /PID $processId /T /F *> $null
+  }
+}
+
+function Stop-ListeningProcess([int] $port) {
+  $connections = Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue
+  $connections | Select-Object -ExpandProperty OwningProcess -Unique | ForEach-Object {
+    Stop-ProcessTree $_
+  }
+}
+
+$workspace = Get-WorkspacePath
+$defaultPort = <%= port %>
+$port = if ($env:DEPLOY_RUN_PORT) { [int] $env:DEPLOY_RUN_PORT } elseif ($env:PORT) { [int] $env:PORT } else { $defaultPort }
+Set-Location $workspace
+Stop-ListeningProcess $port
+
+<% if (process.env.NODE_ENV === 'test') { %>
+$env:PORT = "$port"
+& pnpm tsx watch src/server.ts
+exit $LASTEXITCODE
+<% } else { %>
+$logDirectory = if ($env:COZE_LOG_DIR) { $env:COZE_LOG_DIR } else { Join-Path $workspace "logs" }
+$logFile = Join-Path $logDirectory "server.log"
+$errorLogFile = Join-Path $logDirectory "server-error.log"
+$pidFile = Join-Path $logDirectory "server.pid"
+New-Item -ItemType Directory -Force -Path $logDirectory | Out-Null
+
+if (Test-Path $pidFile) {
+  Stop-ProcessTree ([int] (Get-Content $pidFile -Raw))
+  Remove-Item $pidFile -Force
+}
+
+$previousPort = $env:PORT
+$env:PORT = "$port"
+try {
+  $process = Start-Process -FilePath $env:ComSpec -ArgumentList @("/d", "/s", "/c", "pnpm tsx watch src/server.ts") -WorkingDirectory $workspace -RedirectStandardOutput $logFile -RedirectStandardError $errorLogFile -PassThru
+} finally {
+  if ($null -eq $previousPort) { Remove-Item Env:PORT -ErrorAction SilentlyContinue } else { $env:PORT = $previousPort }
+}
+
+$process.Id | Set-Content $pidFile
+Start-Sleep -Seconds 1
+if ($process.HasExited) {
+  Get-Content $errorLogFile -Tail 20 -ErrorAction SilentlyContinue
+  Remove-Item $pidFile -Force -ErrorAction SilentlyContinue
+  exit 1
+}
+
+Write-Host "Dev server started (PID: $($process.Id))."
+Write-Host "Log file: $logFile"
+<% } %>

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

@@ -32,8 +32,89 @@ kill_port_if_listening() {
     fi
 }
 
+<% if (process.env.NODE_ENV === 'test') { %>
+echo "Clearing port ${DEPLOY_RUN_PORT} before start."
+kill_port_if_listening
+echo "Starting HTTP service on port ${DEPLOY_RUN_PORT} for dev..."
+
+# 测试环境保持服务为前台进程，便于 e2e 收集输出并停止进程。
+exec env PORT="${DEPLOY_RUN_PORT}" pnpm tsx watch src/server.ts
+<% } else { %>
+LOG_DIR="${COZE_LOG_DIR:-${COZE_WORKSPACE_PATH}/logs}"
+LOG_FILE="${LOG_DIR}/server.log"
+PID_FILE="${LOG_DIR}/server.pid"
+
+# coze-daemon 会在 runtime shell 退出时清理原进程组。
+# 通过 Node detached spawn 创建独立 session/进程组，并将 stdio 直接写入日志。
+spawn_detached() {
+  local cwd="$1"
+  local log_file="$2"
+  shift 2
+
+  node - "$cwd" "$log_file" "$@" <<'NODE'
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+
+const [cwd, logFile, command, ...args] = process.argv.slice(2);
+if (!cwd || !logFile || !command) {
+  throw new Error('spawn_detached 缺少 cwd、log_file 或 command');
+}
+
+const logFd = fs.openSync(logFile, 'a');
+try {
+  const child = spawn(command, args, {
+    cwd,
+    detached: true,
+    env: process.env,
+    stdio: ['ignore', logFd, logFd],
+  });
+  child.unref();
+  process.stdout.write(String(child.pid));
+} finally {
+  fs.closeSync(logFd);
+}
+NODE
+}
+
+stop_detached() {
+  local pid="${1:-}"
+  if [[ -z "${pid}" ]]; then
+    return
+  fi
+
+  kill -TERM -- "-${pid}" 2>/dev/null || kill -TERM "${pid}" 2>/dev/null || true
+  sleep 1
+  kill -KILL -- "-${pid}" 2>/dev/null || true
+}
+
+# 监听端口的是孙进程（pnpm -> tsx -> node），只清端口会漏掉上层 pnpm/tsx，
+# 所以先按上次记录的 PID 把整个进程组回收掉。
+if [[ -f "${PID_FILE}" ]]; then
+  stop_detached "$(cat "${PID_FILE}" 2>/dev/null || true)"
+  rm -f "${PID_FILE}"
+fi
+
 echo "Clearing port ${DEPLOY_RUN_PORT} before start."
 kill_port_if_listening
 echo "Starting HTTP service on port ${DEPLOY_RUN_PORT} for dev..."
 
-PORT=${DEPLOY_RUN_PORT} pnpm tsx watch src/server.ts
+mkdir -p "${LOG_DIR}"
+: > "${LOG_FILE}"
+
+export PORT="${DEPLOY_RUN_PORT}"
+server_pid="$(spawn_detached "${COZE_WORKSPACE_PATH}" "${LOG_FILE}" \
+  "$(command -v pnpm)" tsx watch src/server.ts)"
+echo "${server_pid}" > "${PID_FILE}"
+
+sleep 1
+if [[ -z "${server_pid}" ]] || ! kill -0 "${server_pid}" 2>/dev/null; then
+  echo "Dev server failed to start. See ${LOG_FILE}." >&2
+  tail -n 20 "${LOG_FILE}" >&2 || true
+  rm -f "${PID_FILE}"
+  exit 1
+fi
+
+echo "Dev server started (PID: ${server_pid})."
+echo "Log file: ${LOG_FILE}"
+echo "PID file: ${PID_FILE}"
+<% } %>

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

@@ -0,0 +1,18 @@
+$ErrorActionPreference = "Stop"
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+Set-Location $workspace
+
+Write-Host "Installing dependencies..."
+& pnpm install --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
+if ($LASTEXITCODE -ne 0) {
+  exit $LASTEXITCODE
+}
+
+if (Get-Command coze-dev -ErrorAction SilentlyContinue) {
+  & coze-dev check-bins --help *> $null
+  if ($LASTEXITCODE -eq 0) {
+    & coze-dev check-bins --fix
+    exit $LASTEXITCODE
+  }
+}

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

@@ -0,0 +1,11 @@
+$ErrorActionPreference = "Stop"
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+$defaultPort = <%= port %>
+$port = if ($env:DEPLOY_RUN_PORT) { $env:DEPLOY_RUN_PORT } elseif ($env:PORT) { $env:PORT } else { $defaultPort }
+Set-Location $workspace
+
+Write-Host "Starting HTTP service on port $port for deploy..."
+$env:PORT = "$port"
+& node dist/server.js
+exit $LASTEXITCODE

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

@@ -0,0 +1,8 @@
+$ErrorActionPreference = "Stop"
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+Set-Location $workspace
+
+Write-Host "Running validate..."
+& pnpm validate
+exit $LASTEXITCODE

package/lib/__templates__/nextjs/template.config.js

@@ -3,6 +3,7 @@
 import { spawn } from 'child_process';
 import { resolve, join, basename } from 'path';
 import { appendFileSync, openSync, closeSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
 
 
 
@@ -74,7 +75,8 @@ const config = {
       const projectRoot = resolve(outputPath);
 
       // Determine log directory
-      const logDir = process.env.COZE_LOG_DIR || resolve(__dirname, '../.log');
+      const cozeHome = process.env.COZE_HOME || join(homedir(), '.coze');
+      const logDir = process.env.COZE_LOG_DIR || join(cozeHome, 'logs');
       mkdirSync(logDir, { recursive: true });
 
       // Use project name in log file to avoid conflicts

package/lib/__templates__/nuxt-vue/.coze

@@ -4,11 +4,16 @@ project_type = "web"
 
 [dev]
 build = ["bash", "./scripts/prepare.sh"]
+build_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/prepare.ps1"]
 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
 
 [deploy]
 build = ["bash","./scripts/build.sh"]
+build_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/build.ps1"]
 run = ["bash","./scripts/start.sh"]
+run_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/start.ps1"]
 deps = ["git"] # -> apt install git

package/lib/__templates__/nuxt-vue/scripts/build.ps1

@@ -0,0 +1,12 @@
+$ErrorActionPreference = "Stop"
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+Set-Location $workspace
+
+Write-Host "Installing dependencies..."
+& pnpm install --prefer-frozen-lockfile --prefer-offline --loglevel debug --reporter=append-only
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+Write-Host "Building the Nuxt.js project..."
+& pnpm nuxt build
+exit $LASTEXITCODE

package/lib/__templates__/nuxt-vue/scripts/dev.ps1

@@ -0,0 +1,63 @@
+$ErrorActionPreference = "Stop"
+
+function Get-WorkspacePath {
+  if ($env:COZE_WORKSPACE_PATH) {
+    return $env:COZE_WORKSPACE_PATH
+  }
+  return (Get-Location).Path
+}
+
+function Stop-ProcessTree([int] $processId) {
+  if ($processId -gt 0 -and (Get-Process -Id $processId -ErrorAction SilentlyContinue)) {
+    & taskkill.exe /PID $processId /T /F *> $null
+  }
+}
+
+function Stop-ListeningProcess([int] $port) {
+  $connections = Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue
+  $connections | Select-Object -ExpandProperty OwningProcess -Unique | ForEach-Object {
+    Stop-ProcessTree $_
+  }
+}
+
+$workspace = Get-WorkspacePath
+$defaultPort = <%= port %>
+$port = if ($env:DEPLOY_RUN_PORT) { [int] $env:DEPLOY_RUN_PORT } elseif ($env:PORT) { [int] $env:PORT } else { $defaultPort }
+Set-Location $workspace
+Stop-ListeningProcess $port
+
+<% if (process.env.NODE_ENV === 'test') { %>
+$env:PORT = "$port"
+& pnpm nuxt dev
+exit $LASTEXITCODE
+<% } else { %>
+$logDirectory = if ($env:COZE_LOG_DIR) { $env:COZE_LOG_DIR } else { Join-Path $workspace "logs" }
+$logFile = Join-Path $logDirectory "server.log"
+$errorLogFile = Join-Path $logDirectory "server-error.log"
+$pidFile = Join-Path $logDirectory "server.pid"
+New-Item -ItemType Directory -Force -Path $logDirectory | Out-Null
+
+if (Test-Path $pidFile) {
+  Stop-ProcessTree ([int] (Get-Content $pidFile -Raw))
+  Remove-Item $pidFile -Force
+}
+
+$previousPort = $env:PORT
+$env:PORT = "$port"
+try {
+  $process = Start-Process -FilePath $env:ComSpec -ArgumentList @("/d", "/s", "/c", "pnpm nuxt dev") -WorkingDirectory $workspace -RedirectStandardOutput $logFile -RedirectStandardError $errorLogFile -PassThru
+} finally {
+  if ($null -eq $previousPort) { Remove-Item Env:PORT -ErrorAction SilentlyContinue } else { $env:PORT = $previousPort }
+}
+
+$process.Id | Set-Content $pidFile
+Start-Sleep -Seconds 1
+if ($process.HasExited) {
+  Get-Content $errorLogFile -Tail 20 -ErrorAction SilentlyContinue
+  Remove-Item $pidFile -Force -ErrorAction SilentlyContinue
+  exit 1
+}
+
+Write-Host "Nuxt dev server started (PID: $($process.Id))."
+Write-Host "Log file: $logFile"
+<% } %>

package/lib/__templates__/nuxt-vue/scripts/dev.sh

@@ -32,8 +32,89 @@ kill_port_if_listening() {
     fi
 }
 
+<% if (process.env.NODE_ENV === 'test') { %>
+echo "Clearing port ${DEPLOY_RUN_PORT} before start."
+kill_port_if_listening
+echo "Starting Nuxt dev server on port ${DEPLOY_RUN_PORT}..."
+
+# 测试环境保持服务为前台进程，便于 e2e 收集输出并停止进程。
+exec env PORT="${DEPLOY_RUN_PORT}" pnpm nuxt dev
+<% } else { %>
+LOG_DIR="${COZE_LOG_DIR:-${COZE_WORKSPACE_PATH}/logs}"
+LOG_FILE="${LOG_DIR}/server.log"
+PID_FILE="${LOG_DIR}/server.pid"
+
+# coze-daemon 会在 runtime shell 退出时清理原进程组。
+# 通过 Node detached spawn 创建独立 session/进程组，并将 stdio 直接写入日志。
+spawn_detached() {
+  local cwd="$1"
+  local log_file="$2"
+  shift 2
+
+  node - "$cwd" "$log_file" "$@" <<'NODE'
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+
+const [cwd, logFile, command, ...args] = process.argv.slice(2);
+if (!cwd || !logFile || !command) {
+  throw new Error('spawn_detached 缺少 cwd、log_file 或 command');
+}
+
+const logFd = fs.openSync(logFile, 'a');
+try {
+  const child = spawn(command, args, {
+    cwd,
+    detached: true,
+    env: process.env,
+    stdio: ['ignore', logFd, logFd],
+  });
+  child.unref();
+  process.stdout.write(String(child.pid));
+} finally {
+  fs.closeSync(logFd);
+}
+NODE
+}
+
+stop_detached() {
+  local pid="${1:-}"
+  if [[ -z "${pid}" ]]; then
+    return
+  fi
+
+  kill -TERM -- "-${pid}" 2>/dev/null || kill -TERM "${pid}" 2>/dev/null || true
+  sleep 1
+  kill -KILL -- "-${pid}" 2>/dev/null || true
+}
+
+# 监听端口的是孙进程（pnpm -> nuxt -> node），只清端口会漏掉上层 pnpm/nuxt，
+# 所以先按上次记录的 PID 把整个进程组回收掉。
+if [[ -f "${PID_FILE}" ]]; then
+  stop_detached "$(cat "${PID_FILE}" 2>/dev/null || true)"
+  rm -f "${PID_FILE}"
+fi
+
 echo "Clearing port ${DEPLOY_RUN_PORT} before start."
 kill_port_if_listening
 echo "Starting Nuxt dev server on port ${DEPLOY_RUN_PORT}..."
 
-PORT=${DEPLOY_RUN_PORT} pnpm nuxt dev
+mkdir -p "${LOG_DIR}"
+: > "${LOG_FILE}"
+
+export PORT="${DEPLOY_RUN_PORT}"
+server_pid="$(spawn_detached "${COZE_WORKSPACE_PATH}" "${LOG_FILE}" \
+  "$(command -v pnpm)" nuxt dev)"
+echo "${server_pid}" > "${PID_FILE}"
+
+sleep 1
+if [[ -z "${server_pid}" ]] || ! kill -0 "${server_pid}" 2>/dev/null; then
+  echo "Dev server failed to start. See ${LOG_FILE}." >&2
+  tail -n 20 "${LOG_FILE}" >&2 || true
+  rm -f "${PID_FILE}"
+  exit 1
+fi
+
+echo "Dev server started (PID: ${server_pid})."
+echo "Log file: ${LOG_FILE}"
+echo "PID file: ${PID_FILE}"
+<% } %>

package/lib/__templates__/nuxt-vue/scripts/prepare.ps1

@@ -0,0 +1,12 @@
+$ErrorActionPreference = "Stop"
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+Set-Location $workspace
+
+Write-Host "Installing dependencies..."
+& pnpm install --prefer-frozen-lockfile --prefer-offline
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+Write-Host "Preparing Nuxt..."
+& pnpm exec nuxt prepare
+exit $LASTEXITCODE

package/lib/__templates__/nuxt-vue/scripts/start.ps1

@@ -0,0 +1,11 @@
+$ErrorActionPreference = "Stop"
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+$defaultPort = <%= port %>
+$port = if ($env:DEPLOY_RUN_PORT) { $env:DEPLOY_RUN_PORT } elseif ($env:PORT) { $env:PORT } else { $defaultPort }
+Set-Location $workspace
+
+Write-Host "Starting Nuxt.js service on port $port for production..."
+$env:PORT = "$port"
+& node .output/server/index.mjs
+exit $LASTEXITCODE

package/lib/__templates__/nuxt-vue/scripts/validate.ps1

@@ -0,0 +1,8 @@
+$ErrorActionPreference = "Stop"
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+Set-Location $workspace
+
+Write-Host "Running validate..."
+& pnpm validate
+exit $LASTEXITCODE

package/lib/__templates__/phaser/.coze

@@ -5,9 +5,14 @@ game_type = "phaser"
 
 [dev]
 build = ["bash", "./scripts/prepare.sh"]
+build_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/prepare.ps1"]
 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"]
 
 [deploy]
 build = ["bash", "./scripts/build.sh"]
+build_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/build.ps1"]
 run = ["bash", "./scripts/start.sh"]
+run_win = ["powershell.exe", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "./scripts/start.ps1"]

package/lib/__templates__/phaser/README.md

@@ -35,3 +35,11 @@ coze-dev start     # 预览生产构建
 - 开发和生产都使用稳定的 `assets/...` 路径，生产构建原样复制素材目录。
 
 `IMAGES`、`IMAGE_SEQUENCES`、`VIDEOS` 和 `AUDIOS` 是四个素材分类表。
+
+## 可视化编辑标识
+
+用 `markEditable` 标记可在编辑器中调整的对象；第三个参数可选，仅用于编辑器展示名称：
+
+```ts
+markEditable('ui.start-button', button, { label: '开始按钮' });
+```

package/lib/__templates__/phaser/_gitignore

@@ -8,6 +8,7 @@ coverage/
 
 *.log
 *.tsbuildinfo
+logs/
 .vite/
 .cache/
 node-compile-cache/

package/lib/__templates__/phaser/package.json

@@ -24,7 +24,7 @@
     "typescript": "^5.9.3",
     "vite": "^8.2.0"
   },
-  "packageManager": "pnpm@9.15.9",
+  "packageManager": "pnpm@9.0.0",
   "engines": {
     "pnpm": ">=9.0.0"
   }

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

@@ -0,0 +1,12 @@
+$ErrorActionPreference = "Stop"
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+Set-Location $workspace
+
+Write-Host "Installing dependencies..."
+& pnpm install --prefer-frozen-lockfile --prefer-offline --reporter=append-only
+if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+
+$env:COZE_PHASER_GAME_ENV = "PROD"
+& pnpm build
+exit $LASTEXITCODE

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

@@ -0,0 +1,49 @@
+$ErrorActionPreference = "Stop"
+
+function Stop-ProcessTree([int] $processId) {
+  if ($processId -gt 0 -and (Get-Process -Id $processId -ErrorAction SilentlyContinue)) {
+    & taskkill.exe /PID $processId /T /F *> $null
+  }
+}
+
+function Stop-ListeningProcess([int] $port) {
+  $connections = Get-NetTCPConnection -LocalPort $port -State Listen -ErrorAction SilentlyContinue
+  $connections | Select-Object -ExpandProperty OwningProcess -Unique | ForEach-Object {
+    Stop-ProcessTree $_
+  }
+}
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+$defaultPort = <%= port %>
+$port = if ($env:DEPLOY_RUN_PORT) { [int] $env:DEPLOY_RUN_PORT } elseif ($env:PORT) { [int] $env:PORT } else { $defaultPort }
+Set-Location $workspace
+Stop-ListeningProcess $port
+$env:COZE_PHASER_GAME_ENV = "DEV"
+
+<% if (process.env.NODE_ENV === 'test') { %>
+& pnpm vite --port $port --host 127.0.0.1 --strictPort
+exit $LASTEXITCODE
+<% } else { %>
+$logDirectory = if ($env:COZE_LOG_DIR) { $env:COZE_LOG_DIR } else { Join-Path $workspace "logs" }
+$logFile = Join-Path $logDirectory "phaser-dev.log"
+$errorLogFile = Join-Path $logDirectory "phaser-dev-error.log"
+$pidFile = Join-Path $logDirectory "phaser-dev.pid"
+New-Item -ItemType Directory -Force -Path $logDirectory | Out-Null
+
+if (Test-Path $pidFile) {
+  Stop-ProcessTree ([int] (Get-Content $pidFile -Raw))
+  Remove-Item $pidFile -Force
+}
+
+$process = Start-Process -FilePath $env:ComSpec -ArgumentList @("/d", "/s", "/c", "pnpm vite --port $port --host 127.0.0.1 --strictPort") -WorkingDirectory $workspace -RedirectStandardOutput $logFile -RedirectStandardError $errorLogFile -PassThru
+$process.Id | Set-Content $pidFile
+Start-Sleep -Seconds 1
+if ($process.HasExited) {
+  Get-Content $errorLogFile -Tail 20 -ErrorAction SilentlyContinue
+  Remove-Item $pidFile -Force -ErrorAction SilentlyContinue
+  exit 1
+}
+
+Write-Host "Phaser dev server started (PID: $($process.Id))."
+Write-Host "Log file: $logFile"
+<% } %>

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

@@ -2,10 +2,81 @@
 set -Eeuo pipefail
 
 COZE_WORKSPACE_PATH="${COZE_WORKSPACE_PATH:-$(pwd)}"
-PORT="${DEPLOY_RUN_PORT:-${PORT:-<%= port %>}}"
+PORT="${PORT:-<%= port %>}"
+DEPLOY_RUN_PORT="${DEPLOY_RUN_PORT:-${PORT}}"
 cd "${COZE_WORKSPACE_PATH}"
 
-COZE_PHASER_GAME_ENV=DEV pnpm vite \
-  --port "${PORT}" \
+get_listening_pids() {
+  local port="$1"
+
+  if command -v lsof >/dev/null 2>&1; then
+    lsof -tiTCP:"${port}" -sTCP:LISTEN 2>/dev/null || true
+  elif command -v ss >/dev/null 2>&1; then
+    ss -H -lntp 2>/dev/null \
+      | awk -v port="${port}" '$4 ~ ":"port"$"' \
+      | grep -o 'pid=[0-9]*' \
+      | cut -d= -f2 \
+      | sort -u || true
+  else
+    echo "Warning: neither lsof nor ss found, cannot check port ${port}." >&2
+  fi
+}
+
+kill_port_if_listening() {
+  local port="$1"
+  local pids
+
+  pids="$(get_listening_pids "${port}")"
+  if [[ -z "${pids}" ]]; then
+    echo "Port ${port} is free."
+    return
+  fi
+
+  echo "Port ${port} is in use by PIDs: ${pids//$'\n'/ } (SIGKILL)"
+  echo "${pids}" | xargs kill -9 2>/dev/null || true
+  sleep 1
+
+  pids="$(get_listening_pids "${port}")"
+  if [[ -n "${pids}" ]]; then
+    echo "Failed to clear port ${port}; remaining PIDs: ${pids//$'\n'/ }." >&2
+    return 1
+  fi
+
+  echo "Port ${port} cleared."
+}
+
+echo "Clearing port ${DEPLOY_RUN_PORT} before start."
+kill_port_if_listening "${DEPLOY_RUN_PORT}"
+
+<% if (process.env.NODE_ENV === 'test') { %>
+# Keep the process attached in tests so the test runner can collect logs and stop it.
+exec env COZE_PHASER_GAME_ENV=DEV pnpm vite \
+  --port "${DEPLOY_RUN_PORT}" \
   --host 127.0.0.1 \
   --strictPort
+<% } else { %>
+LOG_DIR="${COZE_WORKSPACE_PATH}/logs"
+LOG_FILE="${LOG_DIR}/phaser-dev.log"
+PID_FILE="${LOG_DIR}/phaser-dev.pid"
+mkdir -p "${LOG_DIR}"
+
+echo "Starting Phaser dev server on port ${DEPLOY_RUN_PORT}..."
+server_pid="$(COZE_PHASER_GAME_ENV=DEV node scripts/spawn-detached.cjs \
+  "${LOG_FILE}" pnpm vite \
+  --port "${DEPLOY_RUN_PORT}" \
+  --host 127.0.0.1 \
+  --strictPort)"
+echo "${server_pid}" > "${PID_FILE}"
+
+sleep 1
+if ! kill -0 "${server_pid}" 2>/dev/null; then
+  echo "Phaser dev server failed to start. See ${LOG_FILE}." >&2
+  tail -n 20 "${LOG_FILE}" >&2 || true
+  rm -f "${PID_FILE}"
+  exit 1
+fi
+
+echo "Phaser dev server started (PID: ${server_pid})."
+echo "Log file: ${LOG_FILE}"
+echo "PID file: ${PID_FILE}"
+<% } %>

package/lib/__templates__/phaser/scripts/prepare.ps1

@@ -0,0 +1,8 @@
+$ErrorActionPreference = "Stop"
+
+$workspace = if ($env:COZE_WORKSPACE_PATH) { $env:COZE_WORKSPACE_PATH } else { (Get-Location).Path }
+Set-Location $workspace
+
+Write-Host "Installing dependencies..."
+& pnpm install --prefer-frozen-lockfile --prefer-offline --reporter=append-only
+exit $LASTEXITCODE

package/lib/__templates__/phaser/scripts/spawn-detached.cjs

@@ -0,0 +1,29 @@
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+
+const [logFile, command, ...args] = process.argv.slice(2);
+
+if (!logFile || !command) {
+  process.stderr.write(
+    'Usage: node scripts/spawn-detached.cjs <log-file> <command> [...args]\n',
+  );
+  process.exit(1);
+}
+
+const logFd = fs.openSync(logFile, 'a');
+const child = spawn(command, args, {
+  cwd: process.cwd(),
+  detached: process.platform !== 'win32',
+  env: process.env,
+  stdio: ['ignore', logFd, logFd],
+});
+
+fs.closeSync(logFd);
+child.unref();
+
+if (!child.pid) {
+  process.stderr.write('Failed to start detached process.\n');
+  process.exit(1);
+}
+
+process.stdout.write(String(child.pid));