@tbox.cn/app-template-h5 0.1.14 → 0.1.16

package/AGENTS.md

@@ -13,23 +13,26 @@ template-h5 是面向 AI 生成 H5 应用的单 workspace 模板：`apps/client`
 ## 运行与验证（平台沙箱）
 
 应用构建与运行在平台沙箱中，启动/停止/重启由平台负责——不要运行 `pnpm dev` 等长驻进程
-命令（沙箱规则 `config/rules/no-persistent-process.md`）。你只改代码与配置，用一次性命令
-验证：
+命令。你只改代码与配置，用一次性命令验证：
 
 ```sh
 pnpm install       # 会话开始时 node_modules 缺失先装
 pnpm typecheck
 pnpm test
-pnpm build
-pnpm verify        # typecheck + test + lint + build + check:inspector
+pnpm verify:fast   # typecheck + test + check（不含 build/lint）
 pnpm check:inspector  # inspector 接线守卫（随 @tbox.cn/app-sdk-server 分发）
+```
+
+- **编译验证 = typecheck**；运行效果看平台托管的 8000 活体（`curl /api/health`，连接被拒 ≠ 应用损坏）。
+- **不要运行 `pnpm build` / `pnpm verify`**：冷构建超过沙箱命令时限，且 dev 不消费 `dist`。
+- 环境变量见 [README.md](README.md) 的「环境变量」节。
 
 ## SDK 复用点（优先复用，勿手写）
 
 - `@tbox.cn/app-sdk-client`：`configureRuntime`（API base 注入，勿硬编码 host）、`httpGet/httpPost/createService`（HTTP 客户端）、`ErrorBoundary`、`createLogger`、`installGlobalErrorReporting`
 - `@tbox.cn/app-sdk-server`：`createLogger`
 - `@tbox.cn/app-sdk-server/platform`：`installInspector`；vite `code-inspect` 插件入口为 `@tbox.cn/app-sdk-client/platform/code-inspect`（页面微调基线，受 `check:inspector` 守卫）
-- 不直接 import `@tbox-dev-js/sdk`——平台能力一律经 `@tbox.cn/app-sdk-client` / `@tbox.cn/app-sdk-server` 公开入口。开入口。
+- 不直接 import `@tbox-dev-js/sdk`——平台能力一律经 `@tbox.cn/app-sdk-client` / `@tbox.cn/app-sdk-server` 公开入口。
 
 ## 关键入口
 
@@ -46,6 +49,7 @@ apps/server/src/dev.ts                   # vite dev 入口（仅 tsx 运行；
 - 单端口 8000（dev 与生产统一；端口经 `process.env.PORT || 8000`，lint 禁止硬编码）
 - `installInspector` 接线 + `apps/client/index.html` 的 `/__vs_inspector__.js` 标签（页面微调契约）
 - `GET /api/health` 恒返回 `{ "status": "ok" }`；未知 `/api/*` 恒 JSON 404
+- `apps/server/tests` 契约测试随模板分发勿删（health/JSON 404 断言）；client 业务面测试由应用自建——模板出厂零 client 测试文件（`passWithNoTests` 保绿，新增测试后本约定不变）
 - 服务端凭证/环境变量不进 client bundle（客户端环境值仅 `import.meta.env.VITE_*` 且经 `configureRuntime` 注入）
 
 ## web-view 样式约定（嵌入支付宝小程序 web-view 壳时遵守）
@@ -58,6 +62,6 @@ apps/server/src/dev.ts                   # vite dev 入口（仅 tsx 运行；
 ## 边界
 
 - 保持单 workspace 的 `apps/client` + `apps/server` 两成员；不新增 `apps/client/` 之外的 Vite 配置或嵌套 lockfile（`pnpm check:workspace` 校验）。
-- 无模块/Provider/主题装配面：缺双端 `apps/*/src/modules.ts`——`tbox-app module add`、`tbox-app new module`、`tbox-app new provider` 会被 CLI 直接拒绝；`tbox-app theme use` 因无主题接线点也不适用。
+- 无模块/Provider/主题装配面：缺双端 `apps/*/src/modules.ts`——`npx --yes @tbox.cn/app-cli module add`、`npx --yes @tbox.cn/app-cli new module`、`npx --yes @tbox.cn/app-cli new provider` 会被 CLI 直接拒绝；`npx --yes @tbox.cn/app-cli theme use` 因无主题接线点也不适用。
 - 模板不预设端形态（移动/桌面/自适应）——适配策略由应用自定；全局样式挂点 = `apps/client/src/styles/base.css`（仅设备无关卫生规则）。
 - 结构、路由、命令、依赖或环境变量变化时同步 README 与本文件。

package/README.md

@@ -14,7 +14,7 @@ pnpm dev
 ## 生成新应用
 
 ```sh
-tbox-app create . --name my-h5-app --source @tbox.cn/app-template-h5
+npx --yes @tbox.cn/app-cli create . --name my-h5-app --source @tbox.cn/app-template-h5
 pnpm install
 ```
 

package/apps/client/vite.config.ts

@@ -18,4 +18,8 @@ export default defineConfig(({ command }) => ({
   build: {
     rollupOptions: { input: { index: resolve(__dirname, 'index.html') } },
   },
+  // 模板出厂零 client 测试文件：随发测试禁钉用户实施面（business/App.tsx 是用户首个改写对象，
+  // 出厂断言其内容必随应用构建失败——testing/2026-10-20-template-shipped-test-boundary.md）；
+  // 新增客户端测试时移除本旗标。
+  test: { passWithNoTests: true },
 }));

package/apps/server/src/dev.ts

@@ -72,7 +72,7 @@ const vite = await createViteServer({
 });
 
 const runtime = createTboxDevRuntime({
-  vite: { middlewares: vite.middlewares, transformIndexHtml: vite.transformIndexHtml },
+  vite: { middlewares: vite.middlewares, transformIndexHtml: vite.transformIndexHtml, ws: vite.ws },
   hmrHub,
   hmrPath: path.posix.join(vite.config.base, HMR_WS_PATH),
   tokenState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tbox.cn/app-template-h5",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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.26.0"
+    "@tbox.cn/app-sdk-server": "0.26.2"
   },
   "scripts": {
     "dev": "pnpm --filter ./apps/server dev",
@@ -47,6 +47,7 @@
     "verify": "pnpm typecheck && pnpm test && pnpm lint && pnpm build && pnpm check:inspector",
     "check": "pnpm check:workspace && pnpm check:inspector",
     "check:workspace": "node scripts/check-workspace.mjs",
-    "check:inspector": "tbox-inspector-check"
+    "check:inspector": "tbox-inspector-check",
+    "verify:fast": "pnpm typecheck && pnpm test && pnpm check"
   }
 }

package/pnpm-lock.template.yaml

@@ -10,8 +10,8 @@ catalogs:
       specifier: 0.21.3
       version: 0.21.3
     '@tbox.cn/app-sdk-server':
-      specifier: 0.26.0
-      version: 0.26.0
+      specifier: 0.26.2
+      version: 0.26.2
     '@types/express':
       specifier: 4.17.25
       version: 4.17.25
@@ -79,7 +79,7 @@ importers:
     devDependencies:
       '@tbox.cn/app-sdk-server':
         specifier: 'catalog:'
-        version: 0.26.0
+        version: 0.26.2
       eslint:
         specifier: 'catalog:'
         version: 9.39.5
@@ -134,7 +134,7 @@ importers:
     dependencies:
       '@tbox.cn/app-sdk-server':
         specifier: 'catalog:'
-        version: 0.26.0
+        version: 0.26.2
       express:
         specifier: 'catalog:'
         version: 4.22.2
@@ -959,8 +959,12 @@ packages:
     resolution: {integrity: sha512-8sqP/23MoUlbTX9enFNotP5bu7XKFfigDUJ6sEn1Ff2a0rRlSTWzLWmDv9lP70cfZMPjh4MHoLKFoukr8QPvMA==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-contracts@0.13.1':
-    resolution: {integrity: sha512-Cty4qoknyihli6ZMlxOqqTgRqwg0NOh0WOMfIWdB4rHua0QzZkP1jUoeffq5imnpIh7vXdfLhDpv/JwTrHd1XQ==}
+  '@tbox.cn/app-contracts@0.13.2':
+    resolution: {integrity: sha512-0lY9g29ice7xYbmV5XDnEiMmM70jvSzeK2cciUZVpzHgGykWqZiPRlqXIGkIRY7uObDQ1cICHC4mS67HuNQ8Jg==}
+    engines: {node: '>=20.0.0'}
+
+  '@tbox.cn/app-contracts@0.13.3':
+    resolution: {integrity: sha512-P16LFd+ZzIASrujs6fyaOEwRnsLg7Lh5k1qOVDNblmohrvUbVIOK5ntn+7mupJxnjK7SY43RUT4mtWtfM85/rQ==}
     engines: {node: '>=20.0.0'}
 
   '@tbox.cn/app-sdk-client@0.21.3':
@@ -971,13 +975,17 @@ packages:
     resolution: {integrity: sha512-4kcoxnZnPgsO0RwAsjsodOXRhZNQcr9r3INN3Z03/JR2e3E+izkW2YHsgGcdbVSVX81s8gZrkaBbE+xco3wSqg==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-sdk-server@0.26.0':
-    resolution: {integrity: sha512-VpV3sf4K/2MEsnkuK5EqZUyf9KoSVHeJUm4Al0M6R4Wumg6183apnxB2f38S5wuP30JSJShN/ww63EzRniTrjw==}
+  '@tbox.cn/app-sdk-core@0.20.5':
+    resolution: {integrity: sha512-HLLRg1y2jB32uJPL3/a387eABdNZUxrmkGoJwIv44XV9B94DXmTgb9vxYzbyBa0FazxXG0WudyzFnmH5eeqqrw==}
+    engines: {node: '>=20.0.0'}
+
+  '@tbox.cn/app-sdk-server@0.26.2':
+    resolution: {integrity: sha512-TY9oo3VnsHtLv5im9eu9UUBzDJoluk/YRR7MFwU98G1ZzUDoSLagelb0kamhx5j/R9sXZjwV0NY3Kv6dz/WVmw==}
     engines: {node: '>=20.0.0'}
     hasBin: true
 
-  '@tbox.cn/app-toolkit@0.8.0':
-    resolution: {integrity: sha512-urefCf5DCWbH9wM8dSGavA9MNdY4gx7LY16+s9jIlwhahq83mfrCP2h9ombn44ljMrv04G7mnb3vMtNeWs5/Ug==}
+  '@tbox.cn/app-toolkit@0.8.3':
+    resolution: {integrity: sha512-i+rz8tUwndygwCw/T5dp/59p2JKW+Xpfy2UznKOY8vuKbqbe2ANCUTDUuNf8IDuyfvy158Iw/+5H/hLVNAD/3w==}
     engines: {node: '>=20.0.0'}
 
   '@types/babel__core@7.20.5':
@@ -2823,7 +2831,13 @@ snapshots:
       react: 18.3.1
       zod: 3.25.76
 
-  '@tbox.cn/app-contracts@0.13.1':
+  '@tbox.cn/app-contracts@0.13.2':
+    dependencies:
+      '@ag-ui/core': 0.0.47
+      react: 18.3.1
+      zod: 3.25.76
+
+  '@tbox.cn/app-contracts@0.13.3':
     dependencies:
       '@ag-ui/core': 0.0.47
       react: 18.3.1
@@ -2840,19 +2854,23 @@ snapshots:
     dependencies:
       '@tbox.cn/app-contracts': 0.13.0
 
-  '@tbox.cn/app-sdk-server@0.26.0':
+  '@tbox.cn/app-sdk-core@0.20.5':
+    dependencies:
+      '@tbox.cn/app-contracts': 0.13.2
+
+  '@tbox.cn/app-sdk-server@0.26.2':
     dependencies:
       '@ag-ui/core': 0.0.47
-      '@tbox.cn/app-contracts': 0.13.1
-      '@tbox.cn/app-sdk-core': 0.20.4
-      '@tbox.cn/app-toolkit': 0.8.0
+      '@tbox.cn/app-contracts': 0.13.3
+      '@tbox.cn/app-sdk-core': 0.20.5
+      '@tbox.cn/app-toolkit': 0.8.3
       express: 4.22.2
       jose: 6.2.8
       zod: 3.25.76
     transitivePeerDependencies:
       - supports-color
 
-  '@tbox.cn/app-toolkit@0.8.0':
+  '@tbox.cn/app-toolkit@0.8.3':
     dependencies:
       ajv: 8.20.0
       zod: 3.25.76

package/pnpm-workspace.template.yaml

@@ -35,11 +35,11 @@ catalog:
   "@types/express": 4.17.25
   "@tbox.cn/app-sdk-core": 0.20.5
   "@tbox.cn/app-sdk-client": 0.21.3
-  "@tbox.cn/app-sdk-server": 0.26.0
-  "@tbox.cn/app-agent-sdk-server": 0.3.1
+  "@tbox.cn/app-sdk-server": 0.26.2
+  "@tbox.cn/app-agent-sdk-server": 0.3.3
   "@tbox.cn/app-agent-sdk-client": 0.2.0
-  "@tbox.cn/app-contracts": 0.13.2
-  "@tbox.cn/app-contracts-mall": 0.13.1
+  "@tbox.cn/app-contracts": 0.13.3
+  "@tbox.cn/app-contracts-mall": 0.13.2
   eslint: 9.39.5
   typescript-eslint: 8.67.0
   eslint-plugin-react-hooks: 5.2.0

package/scripts/check-workspace.mjs

@@ -31,6 +31,24 @@ const nestedLockfiles = new Set([
 ]);
 const viteConfigPattern = /^vite\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
 
+/**
+ * CLI 裸简写防线：应用文档里不得出现 `tbox-app <cmd>`（agent 照抄后 PATH 无 bin → 命令失败）。
+ * 唯一合法形态 = `npx --yes @tbox.cn/app-cli <cmd>`；`tbox-app-dev`（私有 CLI）不匹配。
+ */
+const bareCliPattern = /\btbox-app\s+(?:module|provider|theme|starter|new|create|schema|skills|doctor|miniapp-container)\b/g;
+const cliDocFiles = ['AGENTS.md', 'README.md', 'ENV.md'];
+
+async function checkCliShorthand(findings) {
+  for (const rel of cliDocFiles) {
+    const file = path.join(projectDir, rel);
+    if (!existsSync(file)) continue;
+    const text = await readFile(file, 'utf8');
+    for (const match of text.matchAll(bareCliPattern)) {
+      findings.bareCliShorthands.push(`${rel}: ${match[0]}`);
+    }
+  }
+}
+
 function relativeDir(filePath) {
   const relative = path.relative(projectDir, path.dirname(filePath));
   return relative === '' ? '.' : relative.split(path.sep).join('/');
@@ -74,6 +92,10 @@ function printFailure(findings) {
     console.error('\n检测到 apps/client/ 之外的 Vite 项目配置：');
     for (const file of findings.detachedViteConfigs) console.error(`  - ${file}`);
   }
+  if (findings.bareCliShorthands.length > 0) {
+    console.error('\n检测到 CLI 裸简写（须写全 npx --yes @tbox.cn/app-cli <cmd>）：');
+    for (const item of findings.bareCliShorthands) console.error(`  - ${item}`);
+  }
 
   console.error('');
   process.exitCode = 1;
@@ -102,9 +124,11 @@ async function main() {
   const findings = {
     nestedLockfiles: [],
     detachedViteConfigs: [],
+    bareCliShorthands: [],
   };
 
   await walk(projectDir, findings);
+  await checkCliShorthand(findings);
 
   if (Object.values(findings).some((items) => items.length > 0)) {
     printFailure(findings);

package/apps/client/src/business/App.test.tsx

@@ -1,18 +0,0 @@
-// @vitest-environment happy-dom
-import { describe, expect, it } from 'vitest';
-import { createRoot } from 'react-dom/client';
-import { flushSync } from 'react-dom';
-import { createElement } from 'react';
-import BusinessApp from './App';
-
-describe('BusinessApp', () => {
-  it('渲染中性入口', () => {
-    const container = document.createElement('div');
-    document.body.appendChild(container);
-    flushSync(() => {
-      createRoot(container).render(createElement(BusinessApp));
-    });
-    expect(container.querySelector('main')?.textContent).toBe('应用从这里开始');
-    container.remove();
-  });
-});