create-lumfall 1.0.0 → 1.1.1

package/templates/document/docs/guide/getting-started.md

@@ -1,199 +0,0 @@
-# 快速开始
-
-从零搭一个最小可运行的 lumfall 业务项目。
-
-## 1. 安装
-
-```sh
-mkdir my-app && cd my-app
-pnpm init
-pnpm add lumfall
-pnpm add -D nodemon concurrently
-```
-
-::: tip 框架共享依赖无需重复安装
-业务页面可以直接 import 框架暴露的共享依赖——`vue`、`@arco-design/web-vue`、
-`vue-router`、`pinia`、`@babel/runtime`、`axios`、`lodash`、`moment`、`md5`。
-框架在 webpack.base 的 `resolve.alias` 里维护这份白名单（指向框架自身的
-依赖目录），无需在业务 `package.json` 里重复安装，且运行时保证只有一份实例
-（需要 lumfall ≥ 1.1.1，白名单见[前端构建](../frontend/build.md)）。
-
-只有框架没有的库才需要自己安装：
-
-```sh
-pnpm add <你的三方库>
-```
-:::
-
-## 2. 服务端入口
-
-`server.js`：
-
-```js
-const { serviceStart } = require("lumfall");
-
-const app = serviceStart({
-  name: "my-app",
-  // 未命中路由时的 302 兜底目标。传了 options 对象就必须显式写 homePath，
-  // 否则兜底会退化为 "/"
-  homePath: "/view/health",
-});
-
-module.exports = app;
-```
-
-框架自带 `health` 页面与接口，此时已经可以启动：
-
-```sh
-_ENV=local node server.js
-# Server running on http://0.0.0.0:3000
-```
-
-访问 `http://localhost:3000/view/health` 看到健康页，
-`http://localhost:3000/health/live` 返回 `{"status":"ok"}`。
-
-::: warning 环境变量是 `_ENV`，不是 `NODE_ENV`
-`_ENV` 的取值是 `local` / `beta` / `prod`（缺省 `local`），决定加载哪份环境配置。
-`NODE_ENV` 对框架配置加载不起作用。
-:::
-
-## 3. 前端构建入口
-
-`build.js`：
-
-```js
-const { frontendBuild } = require("lumfall");
-
-// _ENV=local 启动 Webpack dev server（HMR，默认 127.0.0.1:9002）
-// _ENV=prod  产物构建到 app/public/dist/prod/
-frontendBuild(process.env._ENV);
-```
-
-`package.json` 的 scripts：
-
-```json
-{
-  "scripts": {
-    "dev": "_ENV='local' nodemon --exitcrash server.js",
-    "prod": "_ENV='prod' node server.js",
-    "build:dev": "_ENV='local' node --max_old_space_size=4096 ./build.js",
-    "build:prod": "_ENV='prod' node ./build.js",
-    "start:dev": "concurrently --kill-others-on-fail -n webpack,server -c cyan,green \"pnpm build:dev\" \"pnpm dev\"",
-    "start:prod": "pnpm build:prod && pnpm prod"
-  }
-}
-```
-
-## 4. 写第一个 API
-
-四个文件，目录约定见[目录结构与挂载点](./structure.md)：
-
-`app/service/demo.js`：
-
-```js
-module.exports = (app) => {
-  const BaseService = require("lumfall").Service.Base(app);
-
-  return class DemoService extends BaseService {
-    greeting(name) {
-      return `hello, ${name || "world"}`;
-    }
-  };
-};
-```
-
-`app/controller/demo.js`：
-
-```js
-module.exports = (app) => {
-  const BaseController = require("lumfall").Controller.Base(app);
-
-  return class DemoController extends BaseController {
-    async getGreeting(ctx) {
-      const { demo: demoService } = this.services;
-      const message = demoService.greeting(ctx.request.query.name);
-      await this.success(ctx, { message });
-    }
-  };
-};
-```
-
-`app/router/demo.js`：
-
-```js
-module.exports = (app, router) => {
-  const { demo: demoController } = app.controllers;
-  router.get(
-    "/api/demo/greeting",
-    demoController.getGreeting.bind(demoController)
-  );
-};
-```
-
-`app/router-schema/demo.js`：
-
-```js
-module.exports = {
-  "/api/demo/greeting": {
-    get: {
-      query: {
-        type: "object",
-        properties: {
-          name: { type: "string" },
-        },
-      },
-    },
-  },
-};
-```
-
-重启服务后访问：
-
-```sh
-curl "http://localhost:3000/api/demo/greeting?name=lumfall"
-# {"success":true,"data":{"message":"hello, lumfall"},"metadata":{}}
-```
-
-参数校验不通过时返回 HTTP 200 + `code 442`（详见[路由与参数校验](../core/router-schema.md)）。
-
-## 5. 写第一个页面
-
-推荐用脚手架生成（页面名必须是 kebab-case）：
-
-```sh
-node ./node_modules/lumfall/scripts/generate-page.js hello
-# 生成 app/pages/hello/entry.hello.js + app/pages/hello/hello.vue
-```
-
-也可以手动创建，入口文件 `entry.hello.js`：
-
-```js
-import boot from "$lumfallBoot";
-import Hello from "./hello.vue";
-
-boot(Hello);
-```
-
-页面组件 `hello.vue`：
-
-```vue
-<template>
-  <main class="hello-page">
-    <h1>Hello Lumfall</h1>
-  </main>
-</template>
-```
-
-本地开发时同时起 webpack dev server 与服务：
-
-```sh
-pnpm start:dev
-```
-
-访问 `http://localhost:3000/view/hello`。改组件代码，浏览器热更新。
-
-## 6. 接下来
-
-- [目录结构与挂载点](./structure.md)：把目录约定吃透
-- [配置](./config.md)：按环境组织配置
-- [常见错误自查](../reference/faq.md)：启动失败时先看这里

package/templates/document/docs/guide/introduction.md

@@ -1,55 +0,0 @@
-# 简介
-
-**Lumfall** 是一个基于 Node.js 的全栈框架：服务端是 Koa 2，前端是 Vue 3 + Webpack 5，
-通过 **目录约定** 组织代码，按目录自动加载并挂载，开箱即用。
-
-```sh
-pnpm add lumfall
-```
-
-服务端只需要一个入口文件（`serviceStart()`）；前端由 Webpack 按 `app/pages/` 下的页面入口
-自动多页打包，产物交给 Koa 渲染。业务代码写在自己的项目目录里，框架以 npm 包 `lumfall`
-的形式被依赖。
-
-## 它解决什么问题
-
-搭一个 Koa + Vue 的业务工程，通常要解决一串工程化问题：目录怎么组织、配置怎么分环境、
-路由和参数校验怎么管、前端怎么多页构建、接口安全怎么兜底……Lumfall 把这些固化为约定：
-
-- **目录自动加载**：`app/controller`、`app/service`、`app/router`、`app/middleware`、
-  `app/extend` 下的文件自动扫描、按约定挂载到 `app` 对象上，新建文件即生效
-- **声明式 Dashboard DSL**：Model + Project 两层配置声明整个 B 端管理台；
-  一份字段 schema 驱动搜索栏 / 表格 / 表单 / 详情四个视图，写配置不改代码
-  （见 [DSL 章节](../dsl/overview.md)）
-- **四层配置合并**：框架配置与业务配置按 `_ENV` 环境分层浅合并，支持 JSON Schema 强校验
-- **页面系统**：`app/pages/<name>/entry.<name>.js` 自动发现为页面入口，
-  访问 `/view/<name>`，支持开发热更新（HMR）
-- **前端构建管线**：Webpack 5 多页构建、vendor/common 分包长缓存、
-  `webpack-dev-middleware` + HMR 的开发服务
-- **统一 API 形态**：controller / service 基类 + 统一响应结构 + 基于 JSON Schema 的参数校验
-- **安全策略**：接口签名校验、project_key 校验等内置中间件，配置即用
-- **可观测性**：`/health/live`、`/health/ready` 健康检查探针、请求级 monitoring 钩子、
-  启动产物诊断清单（路由 / 页面 / 探针一览）
-- **插件与生命周期**：数据库、缓存等前置能力以插件注册；启动 / 退出 hook 覆盖全流程
-
-## 适用场景
-
-- 中小型全栈业务系统：管理后台、内容系统、内部工具
-- B 端多项目（多租户）控制台：配合内置 Dashboard 与声明式 DSL，
-  用配置生成整站管理页
-- 需要快速起步、统一团队工程约定的全栈项目
-
-不适合的场景：重 SSR / SEO 的 C 端站点（页面是客户端渲染的 SPA）。
-
-## 快速了解
-
-- 从零建一个项目，看 [快速开始](./getting-started.md)
-- 想直接抄目录骨架，用同工作区的 `lumfall-basic-project/`
-- 声明一个 B 端管理台，看 [DSL 总览](../dsl/overview.md)
-- B 端管理台完整参考（登录、Dashboard、schema 表格表单）看 `lumfall-business/`
-- 技术文档站模板参考 `lumfall-document/`（本站即由它构建）
-
-## 下一步
-
-- [快速开始](./getting-started.md)：十分钟跑起第一个项目
-- [目录结构与挂载点](./structure.md)：框架的核心约定

package/templates/document/docs/guide/structure.md

@@ -1,98 +0,0 @@
-# 目录结构与挂载点
-
-Lumfall 的核心约定：**业务根目录 = 进程的 `process.cwd()`**。
-启动服务与执行构建都必须在业务根目录下运行，否则框架会加载错目录。
-
-## 业务项目结构
-
-```text
-<app-root>/
-├── server.js                  # 服务端入口：serviceStart()
-├── build.js                   # 前端构建入口：frontendBuild(_ENV)
-├── package.json
-├── config/                    # 配置（见「配置」）
-│   ├── config.default.js
-│   ├── config.local.js        # 可选
-│   ├── config.beta.js         # 可选
-│   └── config.prod.js         # 可选
-├── model/                     # 可选，Dashboard 的 Model + Project 配置
-└── app/
-    ├── middleware.js          # 可选，业务全局中间件注册入口
-    ├── middleware/            # 可复用中间件
-    ├── controller/
-    ├── service/
-    ├── router/
-    ├── router-schema/
-    ├── extend/
-    ├── pages/                 # Vue 页面，entry.<name>.js 是入口
-    ├── webpack.config.js      # 可选，扩展 Webpack 配置
-    └── public/                # 静态文件；构建产物在 app/public/dist/
-```
-
-## 挂载点一览
-
-文件名 / 目录名用 `kebab-case` 或 `snake_case`，加载后自动转 `camelCase`。
-
-| 业务目录 | 导出约定 | 挂载结果 |
-| --- | --- | --- |
-| `app/middleware/**/*.js` | `(app) => (ctx, next) => {}` | `app.middlewares.<dir>.<name>` |
-| `app/controller/**/*.js` | `(app) => class` | `app.controllers.<dir>.<name>`，启动时实例化 |
-| `app/service/**/*.js` | `(app) => class` | `app.services.<dir>.<name>`，启动时实例化 |
-| `app/extend/**/*.js` | `(app) => object` | 直接挂到 `app` 上，例如 `app.logger` |
-| `app/router/**/*.js` | `(app, router) => {}` | 注册路由到 `app.router` |
-| `app/router-schema/**/*.js` | schema 对象或 `(app) => map` | 合并进 `app.routerSchema` |
-| `app/middleware.js` | `(app) => { app.use(...) }` | 全局中间件注册入口 |
-| `app/webpack.config.js` | 配置对象 | 与框架 Webpack 配置 `merge.smart` 合并 |
-
-例子：
-
-- `app/service/user-service.js` → `app.services.userService`
-- `app/controller/admin/user-list.js` → `app.controllers.admin.userList`
-- `app/middleware/api/params-verify.js` → `app.middlewares.api.paramsVerify`
-
-框架自带的同名类别文件也会被加载（controller、service、middleware、router-schema、
-router、extend 都有内置实现）；页面入口同名时，**业务页面覆盖框架页面**。
-
-## app 对象上有什么
-
-启动完成后，`serviceStart()` 返回的 `app`（Koa 实例）上至少有：
-
-| 属性 | 说明 |
-| --- | --- |
-| `app.options` | `serviceStart()` 的入参 |
-| `app.baseDir` | `process.cwd()` |
-| `app.businessPath` | `<app-root>/app` 的绝对路径，**业务代码取路径用它，不要用 `__dirname`** |
-| `app.env` | 环境：`app.env.get()` 返回 `_ENV` 值 |
-| `app.middlewares` | 全部中间件（框架 + 业务） |
-| `app.routerSchema` | 合并后的 API 参数校验 schema |
-| `app.controllers` / `app.services` | 已实例化的控制器 / 服务 |
-| `app.config` | 合并后的配置（`configLoader` 之后才存在） |
-| `app.plugins` | 插件注册结果 |
-| `app.router` | KoaRouter 实例 |
-| `app.logger` | 框架日志（log4js） |
-| `app.health` | 健康检查注册器 |
-| `app.diagnostics` | 诊断清单：`app.diagnostics.getManifest()` |
-| `app.server` | `app.listen()` 返回的 server |
-| `app.stop()` | 优雅退出（Promise） |
-
-## 加载规则与三条硬约束
-
-启动流程按固定顺序同步执行（详见 [app 对象与启动流程](../core/app-instance.md)），
-由顺序推出三条约束：
-
-1. **`app.config` 在 controller / service 工厂执行期还不存在**
-   → 只能在请求阶段读配置（基类的 `this.config` getter 是安全的）
-2. **controller 比 service 先加载**
-   → 不要在 controller 工厂或构造期取 `app.services`（请求阶段用 `this.services`）
-3. **任何 loader 遇到非法导出会直接抛错并中断启动**，不会静默跳过
-   → 导出形状必须严格按上表约定
-
-## 路径书写注意
-
-- 业务路径统一走 `app.businessPath` + `path.join` / `path.resolve`，不要硬编码 `/`
-- 例外：`glob` v7 的结果始终是 `/` 分隔，拼接前先按 `/` 拆开再 `join(path.sep)`
-
-## 下一步
-
-- [Controller 与 Service](../core/controller-service.md)：写业务逻辑
-- [路由与参数校验](../core/router-schema.md)：暴露 API

package/templates/document/docs/reference/commands.md

@@ -1,70 +0,0 @@
-# 命令与环境速查
-
-## 命令速查
-
-在业务根目录（`<app-root>`）下执行：
-
-| 场景 | 命令 |
-| --- | --- |
-| 安装依赖 | `pnpm install` |
-| 本地开发（前端 HMR + 服务） | `pnpm start:dev`（= `build:dev` + `dev` 并行） |
-| 只起服务 | `_ENV=local node server.js` |
-| 生产构建 | `_ENV=prod node build.js` |
-| 生产启动 | `_ENV=prod node server.js` |
-| 构建 + 启动 | `pnpm start:prod` |
-| 生成页面 | `pnpm new-page <name> [--header]` 或 `node ./node_modules/lumfall/scripts/generate-page.js <name>` |
-| 排查挂载 | 启动后读 `app.diagnostics.getManifest()` |
-
-`new-page` 的页面名必须是 kebab-case；`--header` 套 HeaderContainer 布局。
-
-## 环境变量
-
-| 变量 | 取值 | 作用 |
-| --- | --- | --- |
-| `_ENV` | `local`（默认）/ `beta` / `prod` | 环境标识，决定加载哪份 `config.<env>.js` 与构建模式 |
-| `PORT` | 默认 3000 | Koa 服务端口 |
-| `IP` | 默认 0.0.0.0 | Koa 监听地址 |
-
-注意：**不是** `NODE_ENV`；`_ENV` 同时决定配置加载与前端构建模式。
-
-## serviceStart 选项
-
-| 选项 | 类型 | 作用 |
-| --- | --- | --- |
-| `name` | string | 应用名（页面 `<title>`） |
-| `homePath` | string | 未命中路由的 302 兜底；传 options 时必须显式声明 |
-| `configSchema` | object | 合并配置的 JSON Schema 校验 |
-| `lifecycle` | object | 启动 / 停止 hook（7 个） |
-| `plugins` | array | 插件描述符 |
-| `monitoring` | object | 请求观测 hook |
-
-## 端口速记
-
-| 端口 | 归属 |
-| --- | --- |
-| 3000 | Koa 服务（`PORT` 可覆盖） |
-| 9002 | Webpack dev server + HMR（仅 `_ENV=local` 构建，写死在框架 `webpack.dev.js`） |
-
-## 错误码速记
-
-| code | 含义 | 来源 |
-| --- | --- | --- |
-| 442 | 参数校验失败 | apiParamsVerify（router-schema） |
-| 445 | 签名校验失败 | apiSignVerify |
-| 446 | 缺 project_key | projectHandler |
-| 5000 | 服务端异常兜底 | errorHandler |
-| 4041 | 页面不存在 | ViewController |
-| 5031 | 页面模板未构建 | ViewController |
-| 50000 | 业务失败约定码 | `this.fail` 示例约定 |
-
-## 框架内置路由
-
-| 路由 | 说明 |
-| --- | --- |
-| `/view/:page`、`/view/:page/*` | 页面渲染 |
-| `/health/live` | 存活探针 |
-| `/health/ready` | 就绪探针 |
-| `/api/project/model_list` | Dashboard Model 列表（免 project_key） |
-| `/api/project/list` | Dashboard 项目列表（免 project_key） |
-| `/api/project` | Dashboard 单项目配置 |
-| 其余未命中 GET | 302 → `homePath` |

package/templates/document/docs/reference/faq.md

@@ -1,94 +0,0 @@
-# 常见错误自查
-
-启动失败或行为不符合预期时，按这份清单排查。
-
-## 启动期
-
-1. **`Class extends value ... is not a constructor`**
-   `Controller.Base` / `Service.Base` 是工厂函数，要调用：
-   `require("lumfall").Controller.Base(app)`，少写 `(app)` 就会这样报错
-
-2. **controller / service 工厂返回了对象而不是 class**
-   loader 直接抛错中断启动；检查 `return class Xxx extends Base { ... }`
-
-3. **router-schema 启动报 `does not match a registered route`**
-   schema 的 key（path）写错、漏写路由，或 method 用了大写
-   （必须小写且确实以该方法注册过）
-
-4. **`[lifecycle] hook "xxx" must be synchronous`**
-   启动期 hook 不能返回 Promise；异步初始化放到 `serviceStart()` 之前做
-   （`beforeStop` / `afterStop` 除外）
-
-5. **`unknown hook "xxx"`**
-   lifecycle 只接受七个 hook 名，见[生命周期](../core/lifecycle.md)
-
-6. **插件报 name 重复 / 缺依赖 / 循环依赖 / register 必须同步**
-   见[插件](../core/plugins.md)规则表
-
-7. **配置校验失败 `merged configuration for "prod" is invalid`**
-   合并后的配置不满足 `configSchema`；注意浅合并是整键替换，
-   环境文件里对象型配置要写完整
-
-8. **extend 报 `must export a factory function`**
-   `app/extend/` 下的文件要导出 `(app) => object`，返回值挂到 app 上
-
-9. **同名页面报 `duplicate business page entry`**
-   同一来源（业务目录）里出现了两个同名 `entry.<name>.js`
-
-## 运行期
-
-10. **配置不生效**
-    - 用的是 `NODE_ENV` 而不是 `_ENV`？环境变量是 `_ENV` ∈ local / beta / prod
-    - 配置是浅合并：环境文件里对象型配置整键替换，可能把 default 的子键覆盖丢了
-    - 在请求阶段读了吗？工厂执行期 `this.config` 是 undefined
-
-11. **挂载点拿不到（undefined）**
-    - 用文件名而不是 camelCase 挂载名？
-      `app.middlewares.apiParamsVerify` 而不是 `app.middlewares["api-params-verify"]`
-    - 用 `__dirname` 拼业务路径？业务路径统一 `app.businessPath`
-
-12. **`/view/<未知页面>` 返回 404 `4041` 而不是跳首页**
-    这是约定：页面不存在是 404 `4041`；页面存在但没构建模板是 503 `5031`；
-    只有**非 /view 的未命中路由**才 302 到 `homePath`
-
-13. **接口返回 `code 442`**
-    router-schema 校验失败，看响应 message 里的具体字段提示
-
-14. **接口返回 `code 445`**
-    签名校验失败：检查 `secret` 是否与客户端一致、时间戳是否过期（`maxAgeMs`）、
-    时间戳是否在未来
-
-15. **接口返回 `code 446`**
-    `/api/project/` 路径缺 `project_key` 头；URL 带 `?projectKey=xxx`
-    时 `$lumfallCurl` 会自动带上
-
-16. **接口返回 `code 5000`**
-    服务端异常被 errorHandler 兜底，详情在日志里（工作区 `logs/` 目录）
-
-17. **页面白屏**
-    - 看浏览器控制台与 Network：JS/CSS 404 说明产物 publicPath 对不上
-      （确认跑过对应模式的构建）
-    - dev 模式资源指向 `127.0.0.1:9002`，先起 `build:dev` 再访问 3000 端口
-
-18. **排查「文件明明写了却没生效」**
-    读诊断清单：`app.diagnostics.getManifest()`，看 `routes` / `pages`
-    里有没有你注册的东西
-
-## 工程与依赖
-
-19. **业务代码 import 框架的传递依赖报模块找不到**
-    lumfall ≥ 1.1.1 起框架已把内置依赖（vue / @arco-design/web-vue / pinia /
-    vue-router / @babel/runtime 等）暴露给业务代码，直接 import 即可；
-    旧版本（≤ 1.1.0）+ pnpm 下需在业务 `package.json` 显式声明（见[快速开始](../guide/getting-started.md)）。
-    框架没有的库仍然要先 `pnpm add`
-
-20. **`frontendBuild("beta")` 什么都不做**
-    构建只支持 `_ENV=local`（dev server）与 `_ENV=prod`（产物）
-
-21. **从错误目录启动 / 构建**
-    业务根目录 = `process.cwd()`；必须在 `<app-root>` 下执行 `node server.js`
-    与构建命令
-
-22. **服务端启动时控制台输出大量内容**
-    lumfall ≥ 1.2.0 启动日志已降级为摘要（各 loader 条目数，不打印配置内容）；
-    若仍看到全量配置 dump，说明框架版本过旧，升级即可

package/templates/document/package.json

@@ -1,36 +0,0 @@
-{
-  "name": "lumfall-document",
-  "version": "1.0.0",
-  "description": "基于 lumfall 的技术文档站模板：导航、侧栏、目录、搜索、暗色模式，对标 VitePress 的使用体验",
-  "main": "server.js",
-  "scripts": {
-    "dev": "_ENV='local' nodemon --exitcrash server.js",
-    "beta": "_ENV='beta' nodemon --exitcrash server.js",
-    "prod": "_ENV='prod' node server.js",
-    "build:dev": "_ENV='local' node --max_old_space_size=4096 ./build.js",
-    "build:prod": "_ENV='prod' node ./build.js",
-    "start:dev": "concurrently --kill-others-on-fail -n webpack,server -c cyan,green \"pnpm build:dev\" \"pnpm dev\"",
-    "start:prod": "pnpm build:prod && pnpm prod",
-    "build:static": "node ./scripts/build-static.js"
-  },
-  "dependencies": {
-    "lumfall": "^1.2.1",
-    "highlight.js": "^11.9.0",
-    "markdown-it": "^14.0.0",
-    "markdown-it-container": "^4.0.0"
-  },
-  "devDependencies": {
-    "concurrently": "^10.0.5",
-    "nodemon": "^3.1.14"
-  },
-  "packageManager": "pnpm@10.30.0",
-  "keywords": [
-    "lumfall",
-    "docs",
-    "documentation",
-    "vitepress",
-    "koa",
-    "vue"
-  ],
-  "license": "ISC"
-}

package/templates/document/scripts/build-static.js

@@ -1,129 +0,0 @@
-/**
- * 静态站点构建脚本：产出可直接托管在 Vercel / Netlify / Nginx 的纯静态目录。
- *
- * 用法：pnpm build:static （等价于 _ENV=prod node build.js + 组装 dist-static/）
- *
- * 文档站是纯前端 SPA：markdown 在构建期打进 bundle，运行时不调用任何接口、
- * 不读取服务端注入的 window.__LUMFALL__，因此可以脱离 Koa 以静态文件部署。
- *
- * 产物结构（dist-static/）：
- *   index.html     "/" 的重定向页 → /view/docs
- *   app.html       应用外壳（由 entry.docs.tpl 转换，占位符替换为静态值）
- *   vercel.json    SPA rewrite（/view/docs/* → app.html）+ 长缓存头
- *   dist/prod/...  构建产物（保持 /dist/prod/ 绝对路径可解析）
- */
-const { spawnSync } = require("child_process");
-const fs = require("fs");
-const path = require("path");
-
-const rootDir = process.cwd();
-const distDir = path.join(rootDir, "app", "public", "dist");
-const outDir = path.join(rootDir, "dist-static");
-
-// 1. 复用生产构建：子进程执行 build.js（_ENV=prod），进程退出即构建完成
-console.log("[static] running production build (build.js) ...\n");
-const build = spawnSync("node", ["build.js"], {
-  stdio: "inherit",
-  env: { ...process.env, _ENV: "prod" },
-});
-if (build.status !== 0) {
-  process.exitCode = build.status || 1;
-  return;
-}
-
-// 2. 组装输出目录（保留 .vercel/ 项目链接目录，否则 vercel link 需要重做。
-//    注意必须在 rmSync 之前把文件内容读进内存——rm 后同名路径会被重建，按路径保存无效）
-const linkDir = path.join(outDir, ".vercel");
-const savedLinkFiles = fs.existsSync(linkDir)
-  ? fs.readdirSync(linkDir).map((name) => ({
-      name,
-      content: fs.readFileSync(path.join(linkDir, name)),
-    }))
-  : null;
-fs.rmSync(outDir, { recursive: true, force: true });
-fs.mkdirSync(path.join(outDir, "dist"), { recursive: true });
-if (savedLinkFiles) {
-  fs.mkdirSync(linkDir, { recursive: true });
-  for (const { name, content } of savedLinkFiles) {
-    fs.writeFileSync(path.join(linkDir, name), content);
-  }
-}
-fs.cpSync(path.join(distDir, "prod"), path.join(outDir, "dist", "prod"), {
-  recursive: true,
-});
-
-// 3. entry.docs.tpl → app.html：把服务端渲染的 __LUMFALL__ 占位换成静态值。
-//    文档站前端不读这些值，保留空对象是为了模板使用方将来加 curl 调接口时行为一致。
-//    同时剥掉 {# ... #} nunjucks 注释——Koa 渲染时会剥离，静态导出不剥会变成
-//    页面顶部的可见文本（浏览器会把 head 里的游离文本挪进 body 渲染）。
-//    lumfall >= 1.2.0 起页面模板按模式分目录，prod 构建产物在 dist/prod/ 下。
-const tplPath = path.join(distDir, "prod", "entry.docs.tpl");
-const tpl = fs
-  .readFileSync(tplPath, "utf8")
-  .replace(/\{#[\s\S]*?#\}/g, "");
-const marker = "window.__LUMFALL__";
-const start = tpl.indexOf(marker);
-if (start < 0) {
-  throw new Error(`[static] ${marker} not found in entry.docs.tpl`);
-}
-const scriptEnd = tpl.indexOf("</script>", start);
-if (scriptEnd < 0) {
-  throw new Error("[static] </script> not found after __LUMFALL__ block");
-}
-
-const staticGlobals = `window.__LUMFALL__ = {
-        name: "lumfall-document",
-        env: "static",
-        options: {},
-        projectKey: "",
-      };`;
-const appHtml = tpl.slice(0, start) + staticGlobals + tpl.slice(scriptEnd);
-fs.writeFileSync(path.join(outDir, "app.html"), appHtml);
-
-// 4. "/" 重定向页：静态托管下没有 302 兜底路由，用 meta refresh + JS 跳到 /view/docs
-fs.writeFileSync(
-  path.join(outDir, "index.html"),
-  `<!DOCTYPE html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="UTF-8" />
-    <title>Lumfall 文档</title>
-    <meta http-equiv="refresh" content="0; url=/view/docs" />
-    <script>location.replace("/view/docs");</script>
-  </head>
-  <body></body>
-</html>
-`
-);
-
-// 5. SPA 路由规则：/view/docs/* 深链接重写到 app.html（文件优先，静态资源不受影响）
-fs.writeFileSync(
-  path.join(outDir, "vercel.json"),
-  JSON.stringify(
-    {
-      rewrites: [
-        { source: "/view/docs", destination: "/app.html" },
-        { source: "/view/docs/:path*", destination: "/app.html" },
-      ],
-      headers: [
-        {
-          // 构建产物带内容 hash，可永久缓存；app.html 不缓存保证发版即生效
-          source: "/dist/prod/(.*)",
-          headers: [
-            { key: "Cache-Control", value: "public, max-age=31536000, immutable" },
-          ],
-        },
-        {
-          source: "/app.html",
-          headers: [{ key: "Cache-Control", value: "no-cache" }],
-        },
-      ],
-    },
-    null,
-    2
-  )
-);
-
-console.log(`\n[static] done → ${path.relative(rootDir, outDir)}`);
-console.log("[static] deploy: cd dist-static && vercel --prod");
-console.log("[static] （或 Vercel 项目设置 Build Command: pnpm build:static, Output Directory: dist-static）");