@tbox.cn/app-template-h5 0.1.4 → 0.1.6

package/README.md

@@ -35,6 +35,8 @@ pnpm install
 | `PORT` | server | 服务端口（默认 8000） |
 | `HOST` | server | 监听地址（默认 0.0.0.0） |
 | `VITE_API_URL` | client | API base（空串/未设 = 同源相对路径）；经 `configureRuntime` 注入 |
+| `TBOX_DEV_TOKEN` | server | 沙箱 dev server 鉴权 token（方案 W；平台运行时注入，**本地无需设置**）：形状 `^[A-Za-z0-9_-]{20,128}$`。在场 → protected 双面裁决——dev 面（凭据 + 浏览器导航/同源信号）完整 vite 能力，static 面（无凭据/跨源子资源）纯 dist + SSE 刷新（`GET /__tbox_dev_hot_reload`），零源码泄漏；缺席 → classic（与历史行为字节级等价）。形状不合规 → fail-closed 全 static |
+| `TBOX_DEV_SSE_KEEPALIVE_MS` | server | protected 面 SSE 心跳间隔 ms（缺省 15000；smoke 覆盖用） |
 
 ## 验收
 

package/apps/server/src/dev.ts

@@ -2,82 +2,122 @@
  * vite dev 入口（仅 tsx 运行：pnpm dev；物理不进 tsup bundle——forbid-vite 插件拦截）。
  * middlewareMode + 单端口 8000：HTTP 与 HMR WS 全走应用端口。
  * 部署形态一律走 dist/index.js（静态产物，零 HMR WS）。
+ *
+ * 方案 W（沙箱 dev server 鉴权保护）：TBOX_DEV_TOKEN 在场 → protected 双面裁决
+ * （dev 面 = 凭据 + 导航/同源信号放行 vite；static 面 = 纯 dist + SSE 刷新，零源码泄漏）；
+ * 缺席 → classic，与历史行为字节级等价。裁决机制真源 = SDK platform/dev-runtime
+ * （createTboxDevRuntime），本文件只做装配：vite 实例 + fs.allow 收窄 + 面无关自由区。
  */
 import { createServer } from 'http';
 import path from 'path';
-import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'url';
-import { createServer as createViteServer } from 'vite';
-import { injectScript, installInspector, isReady } from '@tbox.cn/app-sdk-server/platform';
+import { build as viteBuild, createServer as createViteServer, searchForWorkspaceRoot } from 'vite';
+import {
+  createTboxDevRuntime,
+  injectScript,
+  installInspector,
+  isReady,
+  resolveDevTokenFromEnv,
+} from '@tbox.cn/app-sdk-server/platform';
+import { createLogger } from '@tbox.cn/app-sdk-server';
 import { app, start } from './app.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const serverLogger = createLogger('server');
 const clientRoot = path.resolve(__dirname, '../../client');
+const appRoot = path.resolve(__dirname, '../..');
 
 // HMR WS 独立路径与协议常量（scripts/smoke-dev-hmr.sh 断言消费，不得改名）：
-// dev 基础设施命名空间（双下划线），与业务命名空间解耦。
+// dev 基础设施命名空间（双下划线），与业务命名空间解耦。协议白名单与 Spanner 子协议
+// 补写内聚于 SDK handleUpgrade（本模板 upgrade 形态 = server.on 直连，见文件尾）。
 const HMR_WS_PATH = '/__vite_hmr';
 
 // HMR WS hub：永不 listen 的纯事件载体。hmr.server 在场 → vite 不自建独立端口，
 // 客户端按页面同源端口连接。vite 对 hub 仅 on/off('upgrade')。
 const hmrHub = createServer();
 
+const tokenState = resolveDevTokenFromEnv(process.env);
+const protectedMode = tokenState.mode === 'protected';
+
+// protected 面 fs.allow 收窄（classic 恒默认不传——红线）：client 源 + 工作区依赖真源
+// （filter(existsSync)：生成应用无 packages/ 时自动滤除，不影响沙箱半径）。
+const workspaceRoot = searchForWorkspaceRoot(clientRoot);
+const fsAllowNarrowed = protectedMode
+  ? [
+      ...new Set(
+        [
+          clientRoot,
+          path.join(appRoot, 'packages'),
+          path.join(appRoot, 'node_modules'),
+          path.join(workspaceRoot, 'packages'),
+          path.join(workspaceRoot, 'node_modules'),
+        ].filter((p) => existsSync(p)),
+      ),
+    ]
+  : undefined;
+
 const vite = await createViteServer({
   root: clientRoot,
   server: {
     middlewareMode: true,
     allowedHosts: true, // 沙箱域名 Host 透传放行（dev-only；dist 物理不含 vite）
-    fs: { deny: ['.env', '.env.*', '*.{crt,pem}', '**/.git/**'] },
+    fs: {
+      ...(fsAllowNarrowed ? { allow: fsAllowNarrowed } : {}),
+      deny: ['.env', '.env.*', '*.{crt,pem}', '**/.git/**'],
+    },
     hmr: { server: hmrHub, path: HMR_WS_PATH },
   },
-  appType: 'custom', // 不加 Vite 自己的 SPA fallback，由下方 app.use('*') 统一处理
+  appType: 'custom', // 不加 Vite 自己的 SPA fallback，HTML 路由由 runtime.final() 统一处理
 });
 
-// 平台微调（inspector）：入口级接线（与 index.ts 对称），须先于 vite middlewares
-installInspector(app);
-
-const viteHmrPath = path.posix.join(vite.config.base, HMR_WS_PATH);
+const runtime = createTboxDevRuntime({
+  vite: { middlewares: vite.middlewares, transformIndexHtml: vite.transformIndexHtml },
+  hmrHub,
+  hmrPath: path.posix.join(vite.config.base, HMR_WS_PATH),
+  tokenState,
+  clientRoot,
+  clientDist: path.join(clientRoot, 'dist'),
+  spaExcludePrefixes: ['/api'],
+  decorateHtml: (html) => (isReady() ? injectScript(html) : html),
+  logger: serverLogger,
+  sseKeepaliveMs: process.env.TBOX_DEV_SSE_KEEPALIVE_MS ? Number(process.env.TBOX_DEV_SSE_KEEPALIVE_MS) : undefined,
+});
 
-app.use(vite.middlewares);
+// 面裁决：dev 面 → vite middlewares；static 面 → next()（落 final 的 dist 静态）
+app.use(runtime.gate);
 
-// HTML 路由兜底：非 /api 一律返回 index.html（经 Vite 转换 + inspector 注入）
-app.use('*', async (req, res, next) => {
-  if (req.originalUrl.startsWith('/api')) {
-    return next();
-  }
-  try {
-    const rawHtml = await readFile(path.join(clientRoot, 'index.html'), 'utf-8');
-    const template = await vite.transformIndexHtml(req.originalUrl, rawHtml);
-    const html = isReady() ? injectScript(template) : template;
-    res.status(200).set({ 'Content-Type': 'text/html' }).end(html);
-  } catch (e) {
-    next(e);
-  }
+// ── 自由区（模板差异 + 应用自定义 middleware；dev/static 两面恒可见）──
+// 平台微调（inspector）：入口级接线（RUNTIME_PATH 路由 + text/html 装配），两面共用
+installInspector(app);
+// 探针路由：smoke-dev-protected.sh ⑩ 断言两面可见性（dev 基础设施，dist 物理不含）
+app.get('/__tbox_dev_freezone_probe', (_req, res) => {
+  res.type('text/plain').send('freezone-ok');
 });
+// ── 自由区结束 ──
+
+app.use(runtime.final);
+
+// protected 面构建通知：watch 增量构建 → BUNDLE_END → SSE 广播 → static 面 reload。
+// fire-and-forget；watch 启动 emptyOutDir 清空 dist 为已定价行为（首建完成前 static 面纯 404）。
+if (protectedMode) {
+  viteBuild({ root: clientRoot, build: { watch: {}, sourcemap: false } })
+    .then((result) => {
+      const watcher = Array.isArray(result) ? result[0] : result;
+      if (!watcher || !('on' in watcher)) return;
+      watcher.on('event', (e) => {
+        if (e.code === 'BUNDLE_END') runtime.notifyBuildEnd();
+      });
+    })
+    .catch((err) => console.error('[dev] watch build failed:', err));
+}
 
 const server = start();
 
-// 升级处理：认领路径 /__vite_hmr（smoke-dev-hmr.sh 断言消费，不得改名）+ 子协议白名单；
-// 其余一律销毁（本模板无业务 WS）。
-// 子协议补写（2026-09-21，同 agent/support 模板——Spanner 网关把 WS 升级的
-// Sec-WebSocket-Protocol 视为 hop-by-hop 在下游拨号时剥除，详见 tbox-app 仓
-// .agents/notes/implemented/bug-fix/2026-09-21-spanner-ws-subprotocol-strip-reload-loop.md）：
-// 无协议头的 HMR 路径升级补写 vite-hmr 让下游握手成立——否则 destroy → WebKit（Safari/iOS
-// 支付宝·微信，宽松接受网关乐观 101）open 即断 → vite-ping 探测恒成 → location.reload()
-// 无限循环（Chrome/Blink 严格校验协议回显恒不 open 免疫）。其余非 vite 协议值仍销毁
-// （smoke ⑤⑥ 语义不变）；网关透传修复落地后补写自动退化为死分支——长留不移除。
+// 升级处理：唯一 WS 入口 = runtime.handleUpgrade（认领 /__vite_hmr + 子协议白名单 +
+// protected token 校验失败 401；其余一律销毁——本模板无业务 WS，smoke-dev-hmr 断言消费）
 server.on('upgrade', (request, socket, head) => {
-  const { pathname } = new URL(request.url || '/', 'http://localhost');
-  if (pathname !== viteHmrPath) {
-    socket.destroy();
-    return;
-  }
-  const protocol = request.headers['sec-websocket-protocol'];
-  if (!protocol) {
-    request.headers['sec-websocket-protocol'] = 'vite-hmr';
-  } else if (protocol !== 'vite-hmr' && protocol !== 'vite-ping') {
+  if (!runtime.handleUpgrade(request, socket, head)) {
     socket.destroy();
-    return;
   }
-  hmrHub.emit('upgrade', request, socket, head);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbox.cn/app-template-h5",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "tbox 移动 H5 全栈模板（单 workspace：apps/client + apps/server），运行时与页面微调经 @tbox.cn/app-sdk。",
   "type": "module",
   "engines": {
@@ -35,7 +35,7 @@
     "eslint-plugin-react-hooks": "5.2.0",
     "typescript-eslint": "8.67.0",
     "vite": "6.4.3",
-    "@tbox.cn/app-sdk-server": "0.21.0"
+    "@tbox.cn/app-sdk-server": "0.22.0"
   },
   "scripts": {
     "dev": "pnpm --filter ./apps/server dev",

package/pnpm-lock.template.yaml

@@ -10,8 +10,8 @@ catalogs:
       specifier: 0.21.1
       version: 0.21.1
     '@tbox.cn/app-sdk-server':
-      specifier: 0.21.0
-      version: 0.21.0
+      specifier: 0.22.0
+      version: 0.22.0
     '@types/express':
       specifier: 4.17.25
       version: 4.17.25
@@ -82,7 +82,7 @@ importers:
     devDependencies:
       '@tbox.cn/app-sdk-server':
         specifier: 'catalog:'
-        version: 0.21.0
+        version: 0.22.0
       eslint:
         specifier: 'catalog:'
         version: 9.39.5
@@ -140,7 +140,7 @@ importers:
     dependencies:
       '@tbox.cn/app-sdk-server':
         specifier: 'catalog:'
-        version: 0.21.0
+        version: 0.22.0
       express:
         specifier: 'catalog:'
         version: 4.22.2
@@ -965,6 +965,10 @@ packages:
     resolution: {integrity: sha512-GFthajvUSE7tY6Y5kLJgg2dRuZQdLfxq/WAEHOh+Q7RTwg7mpuLsWiNhXISkXMAtpxg0RkSgtwyRq33QS0ay3w==}
     engines: {node: '>=20.0.0'}
 
+  '@tbox.cn/app-contracts@0.12.3':
+    resolution: {integrity: sha512-b71WtU1Kk9rC3lwaefb48ymKPgkdb7MJcJQ0lTeUZu/jSNHsqQ4ZZI9ZUbHQ/rzYvWmZbdxe5H94328jAfJoVA==}
+    engines: {node: '>=20.0.0'}
+
   '@tbox.cn/app-sdk-client@0.21.1':
     resolution: {integrity: sha512-hN+tIj8kh11PD0HMhq5KUs/nZYjxS+ps3F3HTTmOHWXNXzilYafFxeIWJ1bXKVm1Di5EUIjNaRPUDkP6HAcHvw==}
     engines: {node: '>=20.0.0'}
@@ -973,13 +977,17 @@ packages:
     resolution: {integrity: sha512-hvdcXntg4iJniVu9LEwo5A/vov3L08kRlJLTgStYRdAlH9AJXWLDxFITMNf7YJX8W+j9wjJmmS7Sv88iswxM+w==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-sdk-server@0.21.0':
-    resolution: {integrity: sha512-buiwhnT46Jb1P99UJN1p0ATjRzhFIXIgqIYQDT4aT3fVbmMxWUuAPpFYhM3uTFGx5oPh18/ju3MVz0FxZ5DMCg==}
+  '@tbox.cn/app-sdk-core@0.20.2':
+    resolution: {integrity: sha512-KDcFdIrIEOlwDvIqBu29CzR5vDjt0BCADMBrgrd5WlRqjrPM1/jM/RcaRO6gRuElmQCp5LfsoAkVeYTZE/6rpw==}
+    engines: {node: '>=20.0.0'}
+
+  '@tbox.cn/app-sdk-server@0.22.0':
+    resolution: {integrity: sha512-St5cP43/y/pH/s6ubXX44Rf0wmysL19tZRvTWSUV/0EmO7ouoRmtTzsWHe+XnqkcUnRgfSYm/evRse+K9ATNhg==}
     engines: {node: '>=20.0.0'}
     hasBin: true
 
-  '@tbox.cn/app-toolkit@0.5.0':
-    resolution: {integrity: sha512-ShLYwxsMzhr8V5sjixo4GFGBZbAw4/8CoTnCigrbBcRLtydf2ezLrLDR9jHfi/d5fQworFR5ZBzI7xDSjvR2zA==}
+  '@tbox.cn/app-toolkit@0.7.3':
+    resolution: {integrity: sha512-Tdh1XkqRX0DGvTxflrfgJ4WFVW5wiq9cGOd7hpFrGzQ95mXFiSUKyQMgMtIum8kbReUq+aPI5hv8Z87AugZ1yQ==}
     engines: {node: '>=20.0.0'}
 
   '@types/babel__core@7.20.5':
@@ -2830,6 +2838,12 @@ snapshots:
       react: 18.3.1
       zod: 3.25.76
 
+  '@tbox.cn/app-contracts@0.12.3':
+    dependencies:
+      '@ag-ui/core': 0.0.47
+      react: 18.3.1
+      zod: 3.25.76
+
   '@tbox.cn/app-sdk-client@0.21.1':
     dependencies:
       '@tbox.cn/app-contracts': 0.12.0
@@ -2841,19 +2855,23 @@ snapshots:
     dependencies:
       '@tbox.cn/app-contracts': 0.12.0
 
-  '@tbox.cn/app-sdk-server@0.21.0':
+  '@tbox.cn/app-sdk-core@0.20.2':
+    dependencies:
+      '@tbox.cn/app-contracts': 0.12.3
+
+  '@tbox.cn/app-sdk-server@0.22.0':
     dependencies:
       '@ag-ui/core': 0.0.47
-      '@tbox.cn/app-contracts': 0.12.0
-      '@tbox.cn/app-sdk-core': 0.20.0
-      '@tbox.cn/app-toolkit': 0.5.0
+      '@tbox.cn/app-contracts': 0.12.3
+      '@tbox.cn/app-sdk-core': 0.20.2
+      '@tbox.cn/app-toolkit': 0.7.3
       express: 4.22.2
       jose: 6.2.8
       zod: 3.25.76
     transitivePeerDependencies:
       - supports-color
 
-  '@tbox.cn/app-toolkit@0.5.0':
+  '@tbox.cn/app-toolkit@0.7.3':
     dependencies:
       ajv: 8.20.0
       zod: 3.25.76

package/pnpm-workspace.template.yaml

@@ -33,13 +33,13 @@ catalog:
   "@types/node": 24.13.3
   express: 4.22.2
   "@types/express": 4.17.25
-  "@tbox.cn/app-sdk-core": 0.20.1
+  "@tbox.cn/app-sdk-core": 0.20.2
   "@tbox.cn/app-sdk-client": 0.21.1
-  "@tbox.cn/app-sdk-server": 0.21.0
-  "@tbox.cn/app-agent-sdk-server": 0.1.2
-  "@tbox.cn/app-agent-sdk-client": 0.1.1
-  "@tbox.cn/app-contracts": 0.12.1
-  "@tbox.cn/app-contracts-mall": 0.12.1
+  "@tbox.cn/app-sdk-server": 0.22.0
+  "@tbox.cn/app-agent-sdk-server": 0.1.4
+  "@tbox.cn/app-agent-sdk-client": 0.1.3
+  "@tbox.cn/app-contracts": 0.12.3
+  "@tbox.cn/app-contracts-mall": 0.12.4
   eslint: 9.39.5
   typescript-eslint: 8.67.0
   eslint-plugin-react-hooks: 5.2.0