@tbox.cn/app-template-h5 0.1.0

package/pnpm-workspace.template.yaml

@@ -0,0 +1,54 @@
+# 应用 workspace 模板：tbox-app create 用它生成应用的 pnpm-workspace.yaml。
+# 本文件不触发 workspace root（非 pnpm-workspace.yaml 文件名）。
+# 同步规则（guard-workspace h5 组恒等式校验）：
+# - catalog 键集 = 本模板成员 catalog: 引用并集 ∪ 平台三键（平台完备性：codegen 展开恒改写为 catalog:）；
+#   值与根 pnpm-workspace.yaml 同键全等（sync-catalog 维护）。
+# - 非 catalog 顶层键与根镜像（packages/overrides 除外）。
+packages:
+  - apps/*
+  - packages/*
+
+onlyBuiltDependencies:
+  - esbuild
+
+allowBuilds:
+  esbuild: true
+  lefthook: false
+
+resolvePeersFromWorkspaceRoot: true
+
+# 递归脚本并发上限（pnpm -r 默认 4）：全速并行时多包 vitest worker 独立 transform
+# 同一源码树，CI 峰值内存曾致 V8 fatal（SIGABRT）。本地提速可 CLI 旗标覆盖。
+workspaceConcurrency: 2
+
+catalog:
+  typescript: 5.9.3
+  tsx: 4.23.11
+  vite: 6.4.3
+  vitest: 4.1.10
+  react: 18.3.1
+  react-dom: 18.3.1
+  "@types/react": 18.3.31
+  "@types/react-dom": 18.3.7
+  "@types/node": 24.13.3
+  express: 4.22.2
+  "@types/express": 4.17.25
+  "@tbox.cn/app-sdk": 0.20.0
+  "@tbox.cn/app-contracts": 0.11.0
+  "@tbox.cn/app-contracts-mall": 0.11.0
+  eslint: 9.39.5
+  typescript-eslint: 8.67.0
+  eslint-plugin-react-hooks: 5.2.0
+  tsup: 8.5.1
+  "@vitejs/plugin-react": 4.7.0
+  happy-dom: 20.11.2
+  postcss-pxtorem: 6.1.0
+  supertest: 7.2.2
+  "@types/supertest": 7.2.1
+
+# debug 钉版止血（与根 pnpm-workspace.yaml 同步维护；见 2026-09-16-ci-internal-registry-pollution.md）：
+# 模板锁种子投影会清 overrides 段致 debug 重解析为 4.4.3（R5 子集校验失败），故模板必须同携此键；
+# 段恒居文件末尾——create --local-deps 的 overrides 条目按"并入末尾段"注入（cli/src/commands/create.ts）。
+# 平台修复内网 registry 数据后随根一并移除。
+overrides:
+  "debug@4.4.3": "4.4.1"

package/scripts/build.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+set -e
+
+# Usage: build.sh [--skip-server]
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+cd "$PROJECT_DIR"
+echo "Project directory: $PROJECT_DIR"
+
+export NODE_ENV=production
+
+SKIP_SERVER=false
+for arg in "$@"; do
+  [ "$arg" = "--skip-server" ] && SKIP_SERVER=true
+done
+echo "Skip server: $SKIP_SERVER"
+
+# 零依赖守卫 install 前 fail-fast（幂等毫秒级）
+pnpm check:workspace
+
+echo "Installing dependencies..."
+CI=true pnpm install
+
+# 构建序列单源 = package.json build / build:client（守卫经 check 组合注入）；本脚本只管环境与 install
+if [ "$SKIP_SERVER" = false ]; then
+  pnpm build
+else
+  pnpm build:client
+fi
+
+echo "All builds completed successfully!"

package/scripts/check-workspace.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+const projectDir = path.resolve(process.argv[2] ?? path.join(import.meta.dirname, '..'));
+const allowedViteConfigDirs = new Set(['apps/client']);
+const ignoredDirs = new Set([
+  '.agents',
+  '.claude',
+  '.codex',
+  '.cursor',
+  '.git',
+  '.node',
+  '.pnpm-store',
+  '.tmp',
+  '.vite',
+  'dist',
+  'dist-ssr',
+  'node_modules',
+]);
+const nestedLockfiles = new Set([
+  'bun.lock',
+  'bun.lockb',
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'pnpm-lock.template.yaml',
+  'yarn.lock',
+]);
+const viteConfigPattern = /^vite\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
+
+function relativeDir(filePath) {
+  const relative = path.relative(projectDir, path.dirname(filePath));
+  return relative === '' ? '.' : relative.split(path.sep).join('/');
+}
+
+async function walk(dir, findings) {
+  const entries = await readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!ignoredDirs.has(entry.name)) await walk(fullPath, findings);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+
+    const dirName = relativeDir(fullPath);
+    const relativePath = path.relative(projectDir, fullPath).split(path.sep).join('/');
+
+    if (nestedLockfiles.has(entry.name) && dirName !== '.') {
+      findings.nestedLockfiles.push(relativePath);
+    }
+
+    if (viteConfigPattern.test(entry.name) && !allowedViteConfigDirs.has(dirName)) {
+      findings.detachedViteConfigs.push(relativePath);
+    }
+  }
+}
+
+function printFailure(findings) {
+  console.error('');
+  console.error('[check-workspace] 工程边界校验失败。');
+
+  if (findings.nestedLockfiles.length > 0) {
+    console.error('\n检测到嵌套 lockfile（本项目只允许根 pnpm-lock.yaml）：');
+    for (const file of findings.nestedLockfiles) console.error(`  - ${file}`);
+  }
+  if (findings.detachedViteConfigs.length > 0) {
+    console.error('\n检测到 apps/client/ 之外的 Vite 项目配置：');
+    for (const file of findings.detachedViteConfigs) console.error(`  - ${file}`);
+  }
+
+  console.error('');
+  process.exitCode = 1;
+}
+
+/** 向上查找最近的 pnpm-workspace.yaml（模板目录并入根 workspace 后本目录可无 workspace 文件，属父 workspace 成员） */
+function findWorkspaceFile(dir) {
+  let cur = path.resolve(dir);
+  for (;;) {
+    const f = path.join(cur, 'pnpm-workspace.yaml');
+    if (existsSync(f)) return f;
+    const parent = path.dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+
+async function main() {
+  const workspaceFile = findWorkspaceFile(projectDir);
+  if (!workspaceFile) {
+    console.error('[check-workspace] 缺少 pnpm-workspace.yaml（本目录及父级均未找到）。');
+    process.exitCode = 1;
+    return;
+  }
+
+  const findings = {
+    nestedLockfiles: [],
+    detachedViteConfigs: [],
+  };
+
+  await walk(projectDir, findings);
+
+  if (Object.values(findings).some((items) => items.length > 0)) {
+    printFailure(findings);
+    return;
+  }
+
+  console.log('[check-workspace] 工程边界校验通过（apps/* workspace）');
+}
+
+main().catch((error) => {
+  console.error('[check-workspace] 校验执行失败：', error);
+  process.exitCode = 1;
+});

package/scripts/dev.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+cd "$PROJECT_DIR"
+echo "Project directory: $PROJECT_DIR"
+
+echo "Starting development server..."
+echo "  - http://localhost:8000 (API + 页面 + HMR)"
+# 相对 filter：本脚本在仓内被 pnpm dev h5（native preset）调用，名称 filter 会三模板同名命中
+pnpm --filter ./apps/server dev

package/scripts/prepare.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+cd "$PROJECT_DIR"
+
+echo "Installing dependencies..."
+CI=true pnpm install
+
+echo "Prepare complete!"

package/scripts/start.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+cd "$PROJECT_DIR"
+
+echo "Starting production server..."
+echo "NODE_ENV: $NODE_ENV"
+
+# 相对 filter：仓内直跑时名称 filter 会三模板同名命中
+NODE_ENV=production pnpm --filter ./apps/server start

package/scripts/stop.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# 停止本应用全部进程。杀面收敛原则（docs/postmortem/0001）：
+# 1) cmdline 匹配：锚定本项目路径，逐字符 ERE 字面量化（BSD/GNU 无歧义），[^ ]* 锁单参数
+# 2) 端口定位：只取 LISTEN 态——持有连接的客户端（编排探活/代理父进程）不入杀面
+# PORT 契约：须与启动环境一致（生产形态 cmdline 不含路径，端口是唯一定位手段）
+# 边界：根级浅层 <P>/node_modules/.bin/x 直调形态不在 pattern 内（模板内无此调用形态；.pnpm 深路径匹配）
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+cd "$PROJECT_DIR"
+PORT=${PORT:-8000}
+
+esc_ere() {   # 元字符以 [c] 字面量化；单遍扫描防插入物自污染（BSD \+ 为量词，已实证）。
+  #   特例：^ 用 [\^]——裸置双引擎皆为行首锚（实证），[^] 则是非法未闭合括号表达式；\ 用 [\\]
+  local s="$1" i c out=""
+  for ((i=0; i<${#s}; i++)); do
+    c=${s:$i:1}
+    case $c in
+      '.'|'+'|'*'|'?'|'$'|'('|')'|'{'|'}'|'|'|'['|']') out+="[$c]" ;;
+      '^') out+='[\^]' ;;
+      '\') out+='[\\]' ;;
+      *) out+=$c ;;
+    esac
+  done
+  printf '%s' "$out"
+}
+
+LISTEN_TOOLS_OK=1   # 主作用域预计算（listen_pids 经命令替换运行于子 shell，内赋值不外传——R4b 实证）
+command -v lsof >/dev/null 2>&1 || command -v ss >/dev/null 2>&1 || LISTEN_TOOLS_OK=0
+listen_pids() {   # 两级降级：lsof（macOS 恒有）→ ss（iproute2）；参数化端口便于多端口扩展
+  local p=${1:-$PORT}
+  if command -v lsof >/dev/null 2>&1; then
+    lsof -nP -t -i :"$p" -sTCP:LISTEN 2>/dev/null | sort -u
+  elif command -v ss >/dev/null 2>&1; then
+    ss -ltnpH "sport = :$p" 2>/dev/null | grep -o 'pid=[0-9]*' | cut -d= -f2 | sort -u
+  else
+    echo "Warning: lsof/ss 均不可用，端口清理跳过（cmdline 兜底仍执行）" >&2
+  fi
+}
+
+echo "=== Cleaning up residual processes ==="
+ESC=$(esc_ere "$PROJECT_DIR")
+pkill -TERM -f "$ESC/[^ ]*/node_modules" 2>/dev/null || true   # 先于端口杀：杜绝 watch 复活窗口
+
+PIDS=$(listen_pids "$PORT")
+if [ -n "$PIDS" ]; then
+  echo "=== Stopping server on port $PORT ==="
+  for PID in $PIDS; do echo "Killing process $PID..."; kill -9 "$PID" 2>/dev/null || true; done
+  sleep 1
+  if [ -n "$(listen_pids "$PORT")" ]; then
+    echo "Warning: Port $PORT still in use"
+  else
+    echo "Port $PORT is now free"
+  fi
+elif [ "$LISTEN_TOOLS_OK" = 1 ]; then
+  echo "=== Port $PORT: no listener ==="
+else
+  echo "=== Port $PORT: listener status unknown（定位工具缺失）==="
+fi
+echo "=== All services stopped ==="

package/tsconfig.base.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "incremental": true,
+    "useDefineForClassFields": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  }
+}