openxiangda-cli 2.0.0-alpha.12 → 2.0.0-alpha.120

package/dist/toolchain-capsule.js

@@ -0,0 +1,116 @@
+import { createToolchainCapsule, isOpenXiangdaPackageName, TOOLCHAIN_CAPSULE_MAX_MANIFEST_BYTES, TOOLCHAIN_CAPSULE_MAX_PACKAGE_FILES, ToolchainCapsuleScanLimitError, } from "openxiangda-devkit-core";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export function resolveCliToolchainCapsule(templateRoot = resolveDefaultTemplate()) {
+    const localVersions = readLocalPackageVersions();
+    const versions = new Map();
+    for (const dependency of readTemplateDependencies(templateRoot)) {
+        const value = dependency.specifier.startsWith("workspace:")
+            ? localVersions.get(dependency.name)
+            : dependency.specifier;
+        if (!value || /[<>=*^~| ]/.test(value)) {
+            throw new Error(`OPENXIANGDA_TEMPLATE_CAPSULE_VERSION_UNRESOLVED: ${dependency.name}`);
+        }
+        const previous = versions.get(dependency.name);
+        if (previous && previous !== value) {
+            throw new Error(`OPENXIANGDA_TEMPLATE_CAPSULE_SPLIT: ${dependency.name}`);
+        }
+        versions.set(dependency.name, value);
+    }
+    return createToolchainCapsule(versions, "cli-template");
+}
+export function resolveDefaultTemplate() {
+    const repository = resolve(packageRoot, "../../templates/application");
+    if (existsSync(repository))
+        return repository;
+    return join(packageRoot, "template");
+}
+function readLocalPackageVersions() {
+    const packagesRoot = resolve(packageRoot, "..");
+    const versions = new Map();
+    const self = readManifest(join(packageRoot, "package.json"));
+    if (self &&
+        typeof self.name === "string" &&
+        typeof self.version === "string" &&
+        isOpenXiangdaPackageName(self.name)) {
+        versions.set(self.name, self.version);
+    }
+    for (const entry of readdirSync(packagesRoot, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isDirectory())
+            continue;
+        const manifest = readManifest(join(packagesRoot, entry.name, "package.json"));
+        if (manifest &&
+            typeof manifest.name === "string" &&
+            typeof manifest.version === "string" &&
+            isOpenXiangdaPackageName(manifest.name)) {
+            versions.set(manifest.name, manifest.version);
+        }
+    }
+    return versions;
+}
+function readTemplateDependencies(root) {
+    const dependencies = [];
+    let packageFileCount = 0;
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+            if (["node_modules", "dist", ".openxiangda"].includes(entry.name)) {
+                continue;
+            }
+            const path = join(directory, entry.name);
+            if (entry.isDirectory()) {
+                visit(path);
+                continue;
+            }
+            if (!entry.isFile() || entry.name !== "package.json")
+                continue;
+            packageFileCount += 1;
+            if (packageFileCount > TOOLCHAIN_CAPSULE_MAX_PACKAGE_FILES) {
+                throw new ToolchainCapsuleScanLimitError(`template package.json count exceeds ${TOOLCHAIN_CAPSULE_MAX_PACKAGE_FILES}`);
+            }
+            if (statSync(path).size > TOOLCHAIN_CAPSULE_MAX_MANIFEST_BYTES) {
+                throw new ToolchainCapsuleScanLimitError(`${relative(root, path)} exceeds ${TOOLCHAIN_CAPSULE_MAX_MANIFEST_BYTES} bytes`);
+            }
+            const manifest = readManifest(path);
+            if (!manifest)
+                continue;
+            for (const section of [
+                "dependencies",
+                "devDependencies",
+                "peerDependencies",
+                "optionalDependencies",
+            ]) {
+                const values = manifest[section];
+                if (!values || typeof values !== "object")
+                    continue;
+                for (const [name, specifier] of Object.entries(values)) {
+                    if (!isOpenXiangdaPackageName(name)) {
+                        continue;
+                    }
+                    dependencies.push({
+                        name,
+                        specifier: String(specifier),
+                        packageFile: relative(root, path).replaceAll("\\", "/"),
+                        section,
+                    });
+                }
+            }
+        }
+    };
+    visit(resolve(root));
+    return dependencies.sort((left, right) => left.name.localeCompare(right.name) ||
+        left.packageFile.localeCompare(right.packageFile) ||
+        left.section.localeCompare(right.section));
+}
+function readManifest(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+//# sourceMappingURL=toolchain-capsule.js.map

package/dist/toolchain-capsule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolchain-capsule.js","sourceRoot":"","sources":["../src/toolchain-capsule.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,24 +1,30 @@
 {
   "name": "openxiangda-cli",
-  "version": "2.0.0-alpha.12",
+  "version": "2.0.0-alpha.120",
   "description": "Thin application-level CLI for OpenXiangda 2.0.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "bin": {
-    "openxiangda": "./bin/run.js"
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./run": "./bin/run.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "bin/",
     "dist/",
+    "template/",
     "README.md"
   ],
   "dependencies": {
     "@oclif/core": "4.13.3",
-    "openxiangda-contracts": "2.0.0-alpha.12",
-    "openxiangda-skill-kit": "2.0.0-alpha.12",
-    "create-openxiangda": "2.0.0-alpha.12",
-    "openxiangda-devkit-core": "2.0.0-alpha.12"
+    "openxiangda-contracts": "2.0.0-alpha.58",
+    "openxiangda-devkit-core": "2.0.0-alpha.76",
+    "openxiangda-mcp": "2.0.0-alpha.76",
+    "openxiangda-skill-kit": "2.0.0-alpha.95"
   },
   "devDependencies": {
     "tsx": "4.23.12",
@@ -35,8 +41,9 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node ../../scripts/prune-package-dist.mjs && tsc -p tsconfig.json",
+    "build:release": "node ../../scripts/prune-package-dist.mjs && pnpm build",
     "check": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx --test test/*.test.ts"
+    "test": "node scripts/prepare-template.mjs && tsx --test test/*.test.ts && node ../../scripts/verify-cli-blackbox.mjs"
   }
 }

package/template/.dockerignore

@@ -0,0 +1,23 @@
+node_modules
+**/node_modules
+dist
+**/dist
+coverage
+**/coverage
+playwright-report
+**/playwright-report
+test-results
+**/test-results
+.openxiangda
+**/.openxiangda
+.turbo
+**/.turbo
+.turbopack
+**/.turbopack
+.umi
+**/.umi
+.umi-production
+**/.umi-production
+.git
+*.log
+**/*.log

package/template/.env.example

@@ -0,0 +1,3 @@
+# openxiangda dev injects these values. Do not put platform tokens in this file.
+OPENXIANGDA_APP_CODE=instrument-center
+OPENXIANGDA_DEV_HOST=127.0.0.1

package/template/AGENTS.md

@@ -0,0 +1,25 @@
+# OpenXiangda 2.0 Application Agent Contract
+
+- Use only the workspace-pinned CLI: `pnpm openxiangda <command>`. Never invoke a bare global `openxiangda` inside a 2.0 task.
+- `appspec/` is the optional OpenXiangda 2.0 business-intent layer. Before changing observable behavior, read the bounded index with `pnpm openxiangda spec context --json`, then select only the relevant stable ID; use no ChangeSpec for L0 work, one short ChangeSpec for L1, and add permission/rollback/concurrency detail only for L2/L3. Before close, the user—not AI—confirms `currentSpec=merged` or `not-applicable`. AppSpec is advisory and never a release gate. Never read, import or migrate 1.x `openspec/` or SDD.
+- Use Vite, React Router, Refine Core and Ant Design. Do not add Umi, ProComponents or another admin shell.
+- Bind every generated `appRoutes` entry to its local page with `defineApplicationContributions`; desktop `admin` routes stay inside the platform Shell, while `user` routes render without an admin Shell for independent mobile/user experiences. Generated resource CRUD routes are compiler-owned under `/admin/resources/<resourceCode>...` and `/m/admin/resources/<resourceCode>...`; never recreate root resource paths, aliases or redirects. Explicit routes that have the same canonical shape as another explicit or generated route fail compilation, even when dynamic parameter names differ. Use only the typed `toolbar`, `row` and `detail` resource slots for generated resource actions. Declare the complete editable admin menu with `defineAdminNavigation` and its page/group helpers; the Shell renders only generated `adminNavigation` references and permissions only filter them. Do not create another router, menu store, layout, identity provider, permission store or copied CRUD page; route/action access uses capability or `allOf`/`anyOf`, while Data/App API and Workflow authorization remain server-owned.
+- Declare each resource once in `openxiangda.config.ts` with only `code`, `name`, `fields` and optional `mutationOwner`, generated/list/layout/data-policy settings. Each field owns type, label, required state, Surface flags, reference/file metadata and access. Resource codes are lower kebab-case. Use `native` for direct Data API mutations, `action`, `readonly` or `workflow` for non-Native ownership; never grant or generate Native mutation for a non-Native owner.
+- Never write resource-level `schemaVersion`, `appCode`, `schema`, `surface`, `capabilities`, `fieldPolicies` or `platform/data` modules. The compiler derives the strict DataResource, CRUD capabilities, Surface and AI Schema. The application manifest still starts with its one top-level `schemaVersion: 3`.
+- Ordinary list/get/create/update/delete, filters, export and batch operations use the platform Native Data API. Do not create Function CRUD or NestJS wrappers.
+- Add NestJS only for a named business action that needs a cross-resource transaction, an invariant or an external side effect.
+- Every interactive business action binds `@OpenXiangdaOperation(operation)` and injects `OpenXiangdaBusinessDataApiService`, `OpenXiangdaBusinessNotificationService`, or `OpenXiangdaStandardOperations`. The platform checks the action capability once at App API ingress; the trusted backend then has full Data/managed business-notification access only to its exact application/environment while audit retains the initiating user and action. Do not author `authorizationJSON`, forward user tokens, grant ordinary users `app:notification2:send`, or reapply the user's resource, row and field permissions inside the action.
+- A NestJS backend declares only `enabled`, `isolation: 'shared' | 'dedicated'` and `resourceProfile: 'light' | 'standard'`. Never put raw Kubernetes resources, replicas, ports or environment maps in application metadata; the platform owns capacity and scaling.
+- Use the current logged-in user and the union of that user's application roles. An optional declared Perspective projects only read visibility (pages, rows and fields); create/update/delete, workflows and custom actions continue to authorize against the complete union. Standard Data API calls inherit `X-OpenXiangda-Perspective` automatically. Use `@CurrentPerspective()` only when custom Nest code reads outside the standard Data API, and apply an equivalent read projection explicitly. Business code must not persist a platform Token or authorization result and must not implement a second identity path.
+- Fields inherit the resource read/create/update capabilities. Use field `access` only to tighten them; arrays are all-of and `false` is explicit deny. There is no `write` fallback.
+- Field `type` is semantic, never a hand-authored database type. The supported catalog is exactly `text.short`, `text.long`, `text.rich`, `number.integer`, `number.decimal`, `boolean`, `date`, `time`, `datetime`, `date-range`, `datetime-range`, `option.single`, `option.multiple`, `cascade.single`, `cascade.multiple`, `user.single`, `user.multiple`, `department.single`, `department.multiple`, `resource-ref.single`, `resource-ref.multiple`, `file`, `image`, `signature`, `address`, `location`, `json`, `serial-number`, `uuid` and `subtable`. The compiler alone derives PostgreSQL columns, constraints and indexes.
+- Declare every custom operation capability in `authz.capabilities` with `kind: 'backend'`, then reference that same code from the operation and its allowed roles. Generated resource CRUD capabilities do not go in this catalog.
+- Build App Operation request/response schemas with `resourceRecordSchema`, `schemaRef`, `composeJsonSchema` and `composeAppOperationSchemas` from `openxiangda/config`. They project the same Resource declaration and canonical field value protocols; never import a physical toolchain package or repeat user, department, resource-reference or managed-file schemas by hand.
+- Visitor duplicate protection uses `createVisitorReservation({ duplicateMatch: { fieldCode: submittedValue }, ... })`. `duplicateMatch` is a non-empty value map, never a field-name array, and no mutable pre-read is allowed.
+- Desktop and mobile pages share values, validation and authorization, but use separate renderers. Options, members and departments store display snapshots; resource references store direct JSON display values; attachments, images and signatures use platform-managed file references.
+- `option.*`, `user.*`, `department.*` and `resource-ref.*` values never collapse to scalar IDs. Single values store one labeled object and multiple values store object arrays. `resource-ref.*` JSON is not a foreign key, trusted target snapshot or automatically refreshed copy; current target state is read by `resourceCode` plus `value`. A resource source `labelField` must be `text.short` or `text.long`; `serial-number` is allowed in source search, description and snapshot fields, but not as the label. `location` accepts only exact WGS84 coordinates captured by DingTalk or browser geolocation; it has no manual input or `manual` source. Roles that consume directory-backed fields explicitly include `app:<app-code>:directory:read`.
+- Derive role grants with `resourceCapabilityCodes(appCode, resourceCode)`. Declare current-user rows only with `currentUserDataPolicy(...)`; do not invent operators, values or alternate current-user spellings.
+- Do not add compatibility aliases, migration branches or silent fallbacks for an earlier 2.0 alpha contract. Replace an incorrect contract and regenerate the application.
+- Standard Workflow and Notification Hub are optional 2.0 modules. Enable them only through the canonical `openxiangda.config.ts` declarations and generated clients; declare each Workflow launch as `standalone`, `custom-page`, `hidden-handoff` or `work-center-only`, put only self-contained standalone launch pages in navigation, and bind durable save handlers with `defineWorkflowLaunchContributions` without repeating generated titles. Desktop and mobile standard launch pages load the same canonical Workflow launch Surface. To replace Workflow detail, declare both desktop and mobile `detailRouteCode` values whose routes contain exactly `:instanceId`; Work Center, the application todo center and notification channels consume the platform-resolved paths, while every Surface and command remains server-authorized. Add the standard current-user todo page only with `adminApplicationTodoCenterPage()`; never query Notification Hub management APIs from a user page. Never depend on temporary router location state or copy 1.x workflow/message code, tables, APIs, templates or callbacks into this workspace. Keep ordinary CRUD and application-specific state machines independent of them.
+- Run `pnpm openxiangda check --json` after contract changes and read `data.sealedArtifact`; check never seals, and an older `.openxiangda/build/app-package.json` is not the current check result. Use `pnpm openxiangda accept --plan <file>` only for optional real preproduction identity acceptance; it never blocks delivery. Deploy with `pnpm openxiangda deploy`, inspect with `pnpm openxiangda status` and `pnpm openxiangda logs`, and use the platform rollback command rather than mutating K3s directly.
+- AI-native clients start the workspace protocol through the same pinned binary: `pnpm exec openxiangda --mcp-stdio --cwd <workspace>`. Read `openxiangda://workspace/contracts` or call `contract_describe`; for first-time menu authoring, copy `data.adminNavigationAuthoring.suggestion.expression` once into `frontend.admin.navigation` with its listed `openxiangda/config` imports, then edit that application-owned declaration. Never treat the proposal as runtime discovery. When AppSpec is enabled, also read `openxiangda://workspace/appspec` or call `appspec_context`. Require `aiCatalog` and `aiCatalogDigest` to match the normal compiler output. This is a stdio transport mode, not another application-owned server. Never write an application MCP server, Catalog file, preview store or second authorization path.

package/template/README.md

@@ -0,0 +1,43 @@
+# OpenXiangda 2.0 应用模板
+
+这是干净的资源 CRUD 模板：Vite + React Router + Refine Core + Ant Design 前端、NestJS 平台启动层，以及平台 Data/AuthZ 声明。
+
+```bash
+pnpm openxiangda dev
+```
+
+当前应用只直接依赖一个精确版本的 `openxiangda` 根包，并在 lockfile 中锁定其内部实现包。创建另一个应用时使用当前安装的 OpenXiangda 2.0 Skill 给出的精确根包版本，不使用 `latest`、`alpha` 或全局命令。
+
+`appspec/app.md` 是可选的业务意图总纲，帮助人和 AI 理解当前需求，但不是发布门禁。没有行为变化
+时不写变更；小改动最多维护一份短 ChangeSpec。按需使用
+`pnpm openxiangda spec context --json`、`spec new` 和 `spec close`，不要引入 1.x `openspec/SDD`。
+
+在 `openxiangda.config.ts` 的 `data.resources` 中只声明资源 `code`、`name`、`fields` 和可选列表/布局/数据策略。每个字段一次写完语义 `type`、`label`、`required`、列表/筛选标记、`options`/`source`/`file` 与 `access`；不要再写 `schema`、`surface`、PostgreSQL 类型、资源 capabilities、资源 fieldPolicies 或 `platform/data` 模块。编译器据此生成标准后台列表、筛选、表单、详情、审计、文件上传、独立移动端页面、Data API 查询计划和 AI Schema。
+
+成员、部门分别声明 `user.single`/`user.multiple` 和 `department.single`/`department.multiple`；同应用动态资源声明 `resource-ref.single`/`resource-ref.multiple` 及编译期固定的 `source`。这些字段都保存完整 `{label,value,...}` 显示快照，资源引用还保存 `resourceCode` 和声明的 `snapshot` 字段；查询和权限以稳定 `value` 为比较键。资源来源的 `labelField` 只能引用 `text.short` 或 `text.long`；流水号可用于搜索、描述和快照，不能作为显示标签。需要目录选择器的业务角色必须显式拥有 `app:<app-code>:directory:read` 能力。用 `resourceCapabilityCodes` 生成资源 CRUD 权限，用 `currentUserDataPolicy` 声明唯一的当前用户行规则。
+
+字段组件、CRUD Renderer、Shell、Runtime 与 Data/Directory/File/App Client 都由 `openxiangda/react`、`openxiangda/field-kit` 和 `openxiangda/core` 统一提供，应用模板不复制这些实现。Nest 只在需要复杂事务或外部集成时增加 App API。标准客户端显式携带当前环境、使用同源 Cookie；业务代码不读取或持久化 Token、平台内部身份标识与授权结果。
+
+同一应用的自定义后台页、PC 用户页和移动用户页统一声明在
+`frontend.routes`，再用 `defineApplicationContributions(appRoutes, { pages })`
+逐项绑定本地组件并传给 `OpenXiangdaApplication`。后者是唯一的
+BrowserRouter、RuntimeBoundary、Refine、generated routes 和后台 Shell
+所有者；用户页可以拥有独立布局，但不要再建 router/Shell。要使用通用应用待办中心，
+在显式后台导航组中加入 `adminApplicationTodoCenterPage()`；平台生成
+`/admin/todos` 与 `/m/todos`，只读取当前用户的消息/待办投影并统一解析目标页面。
+
+生成式资源后台路径固定为 `/admin/resources/<resourceCode>...`，移动后台面为
+`/m/admin/resources/<resourceCode>...`；普通根路径和 `/m/...` 产品路径可由显式
+`user` route 使用。生成页内部跳转来自编译后的 `adminPages`，不要手写旧根路径、别名或
+重定向。显式 route 与任一生成 route 的动态路径形状重复时，配置编译会直接失败。
+
+前端一次读取当前登录用户在当前环境的完整应用角色并集和 capability。应用可在 `perspectives` 中声明工作视角；视角只投影页面、行和字段的读取范围，不改变真实身份，也不收窄新增、编辑、删除、流程与自定义动作权限。标准 Data API 自动识别视角；只有绕过标准 Data API 的自定义 Nest 查询才需要通过 `@CurrentPerspective()` 显式实现同等读取投影。字段默认继承资源 read/create/update；`access` 数组为 all-of，`false` 为明确拒绝，无权字段在提交前从 payload 删除。
+
+```bash
+pnpm openxiangda check
+pnpm openxiangda deploy
+pnpm openxiangda status
+pnpm openxiangda logs
+```
+
+`deploy` 使用本模板的 `apps/server/Dockerfile` 自动构建并推送 `linux/amd64` 镜像，再把不可变 digest 写入 AppPackage。纯 CRUD 应用可以保持 backend disabled；复杂事务再启用 Nest。

package/template/_gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+coverage/
+playwright-report/
+test-results/
+.openxiangda/
+.turbo/
+.turbopack/
+.umi/
+.umi-production/
+.codegraph/
+.env
+*.log
+.DS_Store

package/template/apps/server/Dockerfile

@@ -0,0 +1,20 @@
+FROM node:22-alpine AS build
+WORKDIR /workspace
+RUN corepack enable
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml tsconfig.base.json ./
+COPY apps/server/package.json apps/server/package.json
+COPY packages/contracts/package.json packages/contracts/package.json
+RUN node -e "const fs=require('node:fs'); const p=JSON.parse(fs.readFileSync('package.json','utf8')); delete p.devDependencies; fs.writeFileSync('package.json', JSON.stringify(p));"
+RUN pnpm --filter @app/server --filter @app/contracts install --no-frozen-lockfile --ignore-scripts
+COPY apps/server apps/server
+COPY packages/contracts packages/contracts
+RUN pnpm --filter @app/server... build
+RUN pnpm --filter @app/server deploy --prod --legacy --ignore-scripts /output
+
+FROM node:22-alpine AS runtime
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --from=build --chown=1000:1000 /output /app
+USER 1000:1000
+EXPOSE 3000
+CMD ["node", "dist/main.js"]

package/template/apps/server/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@app/server",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/main.ts",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/main.js"
+  },
+  "dependencies": {
+    "@app/contracts": "workspace:*",
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
+    "@nestjs/platform-fastify": "11.1.29",
+    "openxiangda": "2.0.0-alpha.34",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "tsx": "4.23.12",
+    "typescript": "5.9.3"
+  }
+}

package/template/apps/server/src/app.module.ts

@@ -0,0 +1,43 @@
+import { Module } from '@nestjs/common';
+import {
+  eventHandlerManifest,
+  eventSchemas,
+  eventSubscriptionCodes,
+} from '@app/contracts';
+import {
+  OpenXiangdaModule,
+  eventSigningSecretsFromEnvironment,
+} from 'openxiangda/nest';
+
+@Module({
+  imports: [
+    OpenXiangdaModule.forRoot({
+      appCode: process.env.OPENXIANGDA_APP_CODE || 'openxiangda-application',
+      platformBaseUrl:
+        process.env.OPENXIANGDA_PLATFORM_BASE_URL ||
+        'http://127.0.0.1:7001/service',
+      environmentKey:
+        process.env.OPENXIANGDA_ENVIRONMENT_KEY || 'preproduction',
+      environmentId:
+        process.env.OPENXIANGDA_ENVIRONMENT_ID || 'connected-development',
+      appVersionId:
+        process.env.OPENXIANGDA_APP_VERSION_ID || 'connected-development',
+      deploymentRunId:
+        process.env.OPENXIANGDA_DEPLOYMENT_RUN_ID || 'connected-development',
+      environmentHeadRevision: Number(
+        process.env.OPENXIANGDA_ENVIRONMENT_HEAD_REVISION || 1
+      ),
+      backendRevisionId:
+        process.env.OPENXIANGDA_BACKEND_REVISION_ID || 'connected-development',
+      version: process.env.OPENXIANGDA_APP_VERSION || '0.1.0-dev',
+      connectedDevelopment:
+        process.env.OPENXIANGDA_CONNECTED_DEV === 'true',
+      eventHandlerManifest,
+      eventSchemas,
+      eventSigningSecrets: eventSigningSecretsFromEnvironment(
+        eventSubscriptionCodes
+      ),
+    }),
+  ],
+})
+export class AppModule {}

package/template/apps/server/src/main.ts

@@ -0,0 +1,5 @@
+import 'reflect-metadata';
+import { bootstrapOpenXiangdaApplication } from 'openxiangda/nest';
+import { AppModule } from './app.module.js';
+
+await bootstrapOpenXiangdaApplication(AppModule);

package/template/apps/server/test/smoke.test.ts

@@ -0,0 +1,16 @@
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import test from 'node:test';
+
+test('the clean server template only owns platform bootstrap', () => {
+  const source = readFileSync(new URL('../src/app.module.ts', import.meta.url), 'utf8');
+  const main = readFileSync(new URL('../src/main.ts', import.meta.url), 'utf8');
+  assert.match(source, /OpenXiangdaModule\.forRoot/);
+  assert.match(source, /eventHandlerManifest/);
+  assert.match(source, /eventSigningSecretsFromEnvironment/);
+  assert.match(main, /bootstrapOpenXiangdaApplication\(AppModule\)/);
+  assert.doesNotMatch(main, /NestFactory|FastifyAdapter/);
+  const legacyMarkers = ['oauth' + 'Client', 'Workflow', 'instrument' + '-context'];
+  assert.doesNotMatch(source, new RegExp(legacyMarkers.join('|')));
+  assert.doesNotMatch(source, /createData|updateData|deleteData|queryData/);
+});

package/template/apps/server/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "sourceMap": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/template/apps/web/data-api-live.e2e.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="openxiangda-runtime-base" content="/" />
+    <meta name="openxiangda-app-code" content="native-projection-app" />
+    <meta name="openxiangda-environment" content="production" />
+    <title>OpenXiangda Standard Data API Live Acceptance</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/e2e/data-api-live-fixture.tsx"></script>
+  </body>
+</html>

package/template/apps/web/e2e/client-fixture.ts

@@ -0,0 +1,5 @@
+export {
+  requestApplicationApi,
+  searchDirectory,
+  searchResource,
+} from 'openxiangda/core';

package/template/apps/web/e2e/data-api-live-fixture.tsx

@@ -0,0 +1,162 @@
+import { Refine } from '@refinedev/core';
+import { App as AntdApp } from 'antd';
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { MemoryRouter, Route, Routes } from 'react-router-dom';
+import {
+  AppearanceProvider,
+  createApplicationProvider,
+  GeneratedResourcePage,
+  OpenXiangdaResourceDefinitionsProvider,
+  RuntimeBoundary,
+  type GeneratedResourceDefinition,
+} from 'openxiangda/react';
+import 'openxiangda/react/styles.css';
+
+const code = 'field-records';
+const capabilityBase = `app:native-projection-app:data:${code}`;
+const capabilities = {
+  read: `${capabilityBase}:read`,
+  create: `${capabilityBase}:create`,
+  update: `${capabilityBase}:update`,
+  delete: `${capabilityBase}:delete`,
+};
+
+function fieldCapabilities() {
+  return {
+    readCapabilities: [capabilities.read],
+    createCapabilities: [capabilities.create],
+    updateCapabilities: [capabilities.update],
+  };
+}
+
+export const liveDefinition: GeneratedResourceDefinition = {
+  code,
+  name: '字段协议记录',
+  capabilities,
+  surface: {
+    mutationOwner: 'native',
+    generated: {
+      list: true,
+      detail: true,
+      create: true,
+      update: true,
+      delete: true,
+    },
+    fields: {
+      text_short: {
+        label: '标题',
+        type: 'text.short',
+        widget: 'text',
+        requiredHint: true,
+        maxLength: 120,
+        list: true,
+        searchable: true,
+        sortable: true,
+        ...fieldCapabilities(),
+      },
+      option_single: {
+        label: '单选快照',
+        type: 'option.single',
+        widget: 'radio',
+        options: [
+          { label: 'Open', value: 'open' },
+          { label: 'Closed', value: 'closed' },
+        ],
+        list: true,
+        ...fieldCapabilities(),
+      },
+      option_multiple: {
+        label: '多选快照',
+        type: 'option.multiple',
+        widget: 'checkbox',
+        options: [
+          { label: 'Open', value: 'open' },
+          { label: 'Urgent', value: 'urgent' },
+        ],
+        list: true,
+        ...fieldCapabilities(),
+      },
+      location_value: {
+        label: '精确定位',
+        type: 'location',
+        widget: 'location',
+        list: true,
+        ...fieldCapabilities(),
+      },
+    },
+    list: {
+      defaultPageSize: 20,
+      searchableFields: ['text_short'],
+      filterFields: ['option_single'],
+      defaultSort: { field: 'text_short', order: 'asc' },
+    },
+    form: { layout: 'sections' },
+    detail: { layout: 'sections' },
+    mobile: { enabled: true },
+  },
+};
+
+const definitions = { [code]: liveDefinition };
+const provider = createApplicationProvider(definitions);
+const routeBase = `/admin/resources/${code}`;
+const routePaths = {
+  fallback: '/admin',
+  list: routeBase,
+  create: `${routeBase}/new`,
+  detail: `${routeBase}/:id`,
+  edit: `${routeBase}/:id/edit`,
+};
+const initialPath =
+  new URLSearchParams(window.location.search).get('initial') || routeBase;
+
+function resourcePage(mode: 'list' | 'create' | 'edit' | 'detail') {
+  return (
+    <GeneratedResourcePage
+      definition={liveDefinition}
+      mode={mode}
+      paths={routePaths}
+      resourceCode={code}
+    />
+  );
+}
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <OpenXiangdaResourceDefinitionsProvider definitions={definitions}>
+      <AppearanceProvider>
+        <AntdApp>
+          <RuntimeBoundary>
+            <MemoryRouter initialEntries={[initialPath]}>
+            <Refine
+              dataProvider={provider}
+              resources={[
+                {
+                  name: code,
+                  list: routePaths.list,
+                  create: routePaths.create,
+                  edit: routePaths.edit,
+                  show: routePaths.detail,
+                },
+              ]}
+            >
+              <Routes>
+                <Route path={routePaths.list} element={resourcePage('list')} />
+                <Route path={routePaths.create} element={resourcePage('create')} />
+                <Route
+                  path={routePaths.detail}
+                  element={resourcePage('detail')}
+                />
+                <Route
+                  path={routePaths.edit}
+                  element={resourcePage('edit')}
+                />
+              </Routes>
+            </Refine>
+            </MemoryRouter>
+          </RuntimeBoundary>
+        </AntdApp>
+      </AppearanceProvider>
+    </OpenXiangdaResourceDefinitionsProvider>
+  </React.StrictMode>
+);