@taicode/common-server 4.0.0-beta.5 → 4.0.0-beta.7

package/output/core/entries.js

@@ -1,9 +1,9 @@
 import { initServiceUnits } from './boot/lifecycle.js';
 import { attachSignalHandlers } from './boot/signal.js';
-import { buildClients, buildConfig, buildResources, buildServices, createBootContext, createDocumentContext, installShutdownHook, registerCoreStep, registerDocumentCoreStep, registerDocumentRoutersStep, registerDocumentSystemRoutesStep, registerMiddlewares, registerRouters, registerSystemRoutesStep, } from './boot/steps.js';
-import { loadEnvironment, resolveConfigEnv } from './env.js';
+import { buildClients, buildConfig, buildResources, buildServices, createBootContext, createDocumentContext, installShutdownHook, registerCoreStep, registerDocumentCoreStep, registerDocumentRoutersStep, registerDocumentSystemRoutesStep, registerMiddlewares, registerRouters, registerSystemRoutesStep, resolveAppEnv, setupResources, } from './boot/steps.js';
+import { loadEnvironment, resolveConfigEnv, CLEANABLE_ENVS } from './env.js';
 import { SERVER_BRAND } from './types.js';
-export { SERVER_BRAND } from './types.js';
+import { discoverTestDataModules, loadTestData } from './test-support/testdata.js';
 /** 默认监听地址 */
 const DEFAULT_HOST = '0.0.0.0';
 function resolvePort(env) {
@@ -18,36 +18,57 @@ function resolvePort(env) {
  * `defineServer()`（N1 §1）——**纯定义**：产出一个 `Server` 对象，不建连、不起服务。
  *
  * 启动是另一个函数（`startServer`）的事——同一份定义可同时喂给「启动」与「出 spec」
- * （`generateOpenApi`）。调用方**不写泛型**：`R` / `C` / `CL` / `S` 全部从工厂返回类型推导。
+ * （`generateOpenApi`）。
  *
  * ## 怎么用
  *
- * 一个服务**只在 `source/server.ts` 里写一次**，然后在两个地方消费它：
+ * 一个服务**只在 `source/server.ts` 里写一次**，然后在三个地方消费它：
  *
  * ```ts
  * // source/server.ts
  * export const server = defineServer({ app, resources, config, clients, services, middlewares, routers })
  * ```
  * ```ts
- * // source/index.ts —— 启动
- * await startServer(server)
- * ```
- * ```ts
- * // build/openapi-gen.ts —— 出 spec
- * await generateOpenApi(server)
- * ```
- * ```ts
- * // *.test.ts —— 测试
- * const testServer = await createTestServer(server)
+ * await startServer(server)        // source/index.ts —— 启动
+ * await generateOpenApi(server)    // build/openapi-gen.ts —— 出 spec
+ * await createTestServer(server)   // *.test.ts —— 测试
  * ```
  *
  * ## 两条容易踩的规矩
  *
  * - **本函数不读 env、不建连、不读库**。放在模块顶层是安全的：`import { server }` 不会有副作用。
  *   （需要 env 的工具进程自己调 `loadRuntimeEnvironment()`。）
- * - **槽位是六个、恒定不缺**。没有业务路由也要写 `routers: () => {}`；没有外部客户端也要写
- *   `clients: () => ({})`——槽位不留「可省略」分支，省掉一个就会让「这份定义到底声明了什么」
- *   需要靠猜。
+ * - **`clients` 可省略**，其余槽位恒定：没有业务路由也要写 `routers: () => {}`。省略 `clients`
+ *   → 空客户端包。其余槽位不留「可省略」分支，省掉一个就会让「这份定义到底声明了什么」需要靠猜。
+ *
+ * ## 扩展 env（`Env`）：`Env` 是**第一个**泛型，类型声明，不影响加载
+ *
+ * `Env` 排在泛型首位，就是为了能**单独手写**：`defineServer<{ FOO?: string }>({ ... })` 把扩展字段
+ * 的类型并进 `ctx.env`（`resources` / `config` 的 `ctx.env` 上可读、有类型）。不写即 `Env = object`
+ * （无扩展，`ctx.env` 就是 `ConfigEnv`）。
+ *
+ * ⚠️ **TypeScript 限制（务必知道）**：只要**显式写了 `Env`**，其余四个泛型
+ * （`Resources` / `Config` / `Clients` / `Services`）就**不再从工厂推导、一律退化为 `object`**
+ * —— 这是 TS「类型参数全有或全无」的规则，不是本函数能绕过的。后果：`defineServer<MyEnv>({...})`
+ * 产出的 `server` 上，`services` 等类型会塌成 `object`，`testServer.services.xxx` 之类会丢类型。
+ *
+ * 因此两种写法各有适用：
+ * - **要完整推导**（典型业务服务，依赖 `ctx.services` / `testServer.services` 的类型）：**不写泛型**，
+ *   把扩展 env 的类型写在**工厂参数标注**上——`resources: (ctx: ResourcesContext<{ FOO?: string }>) => ...`
+ *   或 point-free 传入参数已标注的命名工厂。这样 `Env` 与其余泛型**一起被推导**，不丢类型。
+ * - **只在意 `Env`、不依赖其余被推导类型**（简单服务 / 测试）：直接 `defineServer<MyEnv>({...})`。
+ *
+ * ⚠️ **只声明类型，不参与加载**：env 的加载完全走框架内置逻辑（dotenv 分层 + 进程注入），框架
+ * **不提供自定义加载**；运行期扩展字段的值就是内置加载后的 `process.env[key]`（字符串直通）。
+ *
+ * ```ts
+ * // 写法一（推荐业务服务用）：不写泛型，Env 从工厂参数标注推导，其余泛型一起推导
+ * function createResources(ctx: ResourcesContext<{ REDIS_KEY_PREFIX?: string }>) { ... }
+ * export const server = defineServer({ app, resources: createResources, config, services, middlewares, routers })
+ *
+ * // 写法二：显式手写 Env（首位）——简单；但其余泛型退化为 object
+ * export const server = defineServer<{ REDIS_KEY_PREFIX?: string }>({ app, resources, config, services, middlewares, routers })
+ * ```
  */
 export function defineServer(config) {
     const server = {
@@ -56,19 +77,13 @@ export function defineServer(config) {
     };
     return server;
 }
-/** 供内部/调试使用：判断是否为 `defineServer()` 产物 */
-export function isServer(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        value.__brand === SERVER_BRAND);
-}
 /**
  * `startServer()`——真正跑起来：构造资源、加载配置、建客户端、建服务、装中间件、注册路由、listen、装信号。
  *
  * 步序**就写在本函数里**，不抽到共享的「按模式分支」的装配器：
  * ```
  * env → resources → core → config → clients → services → services.init() → middlewares
- *     → systemRoutes → routers → onClose → ready → listen/signal
+ *     → systemRoutes → routers → onClose → ready → testdata → listen/signal
  * ```
  *
  * - 最早阶段**固定加载 env**（`.env.dev < .env < .env.local`；`ENV=test` 追加 `.env.test.local`）。
@@ -78,6 +93,16 @@ export function isServer(value) {
  *   而不是同一个入口按环境变量 / 选项改行为。
  * - 硬性要求 `Server`（品牌）产物：传裸 `ServerConfig` 是编译错误。
  *
+ * ## `development` / `test` 下会自动装载 `testdata/`
+ *
+ * 真启动（本地 `pnpm dev`）在 `ready()` 之后、**listen 之前**装载 `<cwd>/testdata` 下的脚本并整体
+ * `load()`（见 `test-support/testdata.ts`）：端口一旦对外，数据必须已经在位。脚本拿到的是装配好的
+ * ctx（`env` + `resources` + `log`），所以它们写数据用的就是被测服务读数据的那份连接。
+ * `ENV` 不在 `CLEANABLE_ENVS` 里（即生产）时**整段跳过**——这是 `startServer` 的唯一一处环境
+ * 分支，且是安静的：生产不需要测试数据，也没有什么东西需要失败。
+ *
+ * `cleanup()` 在 `startServer` 路径上不会被调用：真启动要的就是「数据在」，不是「数据不在」。
+ *
  * ## 怎么用
  *
  * ```ts
@@ -94,13 +119,14 @@ export function isServer(value) {
  * 你**需要**知道的两件事：
  * - 端口只读 env 的 `API_PORT`，**不回退 `PORT`**（`PORT` 属 nginx）。`API_PORT=0` 让内核
  *   分配空闲端口，多实例本地调试靠它。
- * - 失败时已构造的资源会被按固定顺序释放（关闭流程七步），不会漏掉连接池；错误原样抛给
+ * - 失败时已构造的资源会被按固定顺序释放（关闭流程八步），不会漏掉连接池；错误原样抛给
  *   调用方——所以端口占用会让 `startServer` 直接 reject，需要在入口处接住。
  */
 export async function startServer(server) {
-    const env = loadEnvironment();
+    const env = resolveAppEnv(loadEnvironment());
     const ctx = createBootContext(server, env);
-    const { resources, classifyResourceError } = await buildResources(ctx);
+    const { resources, units: resourceUnits, classifyResourceError } = await buildResources(ctx);
+    await setupResources(ctx, resourceUnits);
     await registerCoreStep(ctx, classifyResourceError);
     await buildConfig(ctx, resources);
     const clients = await buildClients(ctx, resources);
@@ -109,7 +135,7 @@ export async function startServer(server) {
     await registerMiddlewares(ctx, services, clients);
     registerSystemRoutesStep(ctx, services);
     await registerRouters(ctx, services, clients);
-    installShutdownHook(ctx, services);
+    installShutdownHook(ctx, services, resourceUnits);
     // 信号处理器「随 listen 装、随 close 卸」。但 Fastify 一旦 listening 就拒绝 `addHook`，
     // 所以 onClose 里的 detach 必须先挂上，处理器本身等 listen 成功后再装。
     let detachSignalHandlers = () => { };
@@ -117,11 +143,24 @@ export async function startServer(server) {
         detachSignalHandlers();
     });
     await ctx.app.ready();
+    // 服务已经完全就绪（路由 / 中间件 / 关闭钩子都装好），现在把开发用样本数据写进去，然后才开门。
+    // 顺序是**装配 → 数据 → listen**：端口一旦对外，第一条请求就必须能看到完整数据；反过来
+    // （先 listen 再 load）会留下一段「端口在响应、数据还没就位」的窗口——本地前端 / 集成脚本
+    // 恰好在这时请求，就是偶发的 404 / 空列表。
+    //
+    // 失败直接冒泡给调用方：`testdata/` 的脚本是服务能正常提供数据的前提，它失败时**不该**把端口
+    // 占着等人发现。非可清理环境（生产）整段跳过——这是本入口唯一的环境分支。
+    if (CLEANABLE_ENVS.includes(env.ENV)) {
+        const units = await discoverTestDataModules();
+        if (units.length > 0) {
+            await loadTestData({ ctx: { env, resources, log: ctx.log }, units, service: ctx.service });
+        }
+    }
     try {
         await ctx.app.listen({ port: resolvePort(env), host: DEFAULT_HOST });
     }
     catch (error) {
-        // 端口占用 / 地址不可用：把已构造的资源按固定七步释放掉，再把错误抛给调用方
+        // 端口占用 / 地址不可用：把已构造的资源按固定八步释放掉，再把错误抛给调用方
         await ctx.app.close();
         throw error;
     }
@@ -173,7 +212,7 @@ export async function startServer(server) {
  * `CONFIG_UNAVAILABLE`——那不是 bug，是在提醒「路由注册期不该依赖运行期产物」。
  */
 export async function generateOpenApi(server) {
-    // 不加载 .env 文件、不读配置
+    // 不加载 .env 文件、不读配置、不跑 `resources` / `config` 槽位（出 spec 不要求 env 有效，也不构造 resources / config）
     const env = resolveConfigEnv();
     const ctx = createDocumentContext(server, env);
     try {

package/output/core/entries.test.js

@@ -2,6 +2,7 @@ import { beforeAll, describe, expect, it, vi } from 'vitest';
 import { createAuthMiddleware } from '../auth/index.js';
 import { defineServer, generateOpenApi, startServer } from './entries.js';
 import { routerSchema } from './modules/schema/builders.js';
+import { defineResource } from './resource.js';
 const IDENTITY = { service: 'probe', title: 'Probe', version: '0.0.0' };
 const ROUTE_SCHEMA = routerSchema({
     operationId: 'probeGet',
@@ -26,11 +27,11 @@ function buildServer(registerPermissionOperations, onMiddlewares = vi.fn()) {
         services: () => ({}),
         middlewares: (ctx) => {
             onMiddlewares();
-            return {
-                auth: createAuthMiddleware(ctx, {
+            return [
+                createAuthMiddleware(ctx, {
                     client: { verify: async () => ({ user: {}, token: 't' }), registerPermissionOperations },
                 }),
-            };
+            ];
         },
         routers: ({ app }) => {
             app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
@@ -45,11 +46,11 @@ function buildStartableServer(registerPermissionOperations) {
         config: () => ({ server: { cookieNames: ['token'] } }),
         clients: () => ({}),
         services: () => ({}),
-        middlewares: (ctx) => ({
-            auth: createAuthMiddleware(ctx, {
+        middlewares: (ctx) => [
+            createAuthMiddleware(ctx, {
                 client: { verify: async () => ({ user: {}, token: 't' }), registerPermissionOperations },
             }),
-        }),
+        ],
         routers: ({ app }) => {
             app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
         },
@@ -95,7 +96,7 @@ describe('generateOpenApi', () => {
                 onServices();
                 return {};
             },
-            middlewares: () => ({}),
+            middlewares: () => [],
             routers: ({ app }) => {
                 app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
             },
@@ -122,7 +123,7 @@ describe('generateOpenApi', () => {
             config: () => ({}),
             clients: () => ({}),
             services: () => ({}),
-            middlewares: () => ({}),
+            middlewares: () => [],
             routers: ({ app }) => {
                 // 故意不声明 schema，验证运行期守卫
                 app.get('/bad', async () => ({ ok: true }));
@@ -173,7 +174,7 @@ describe('startServer', () => {
             },
             middlewares: (ctx) => {
                 seen.middleware = ctx.clients.account;
-                return {};
+                return [];
             },
             routers: (ctx) => {
                 order.push('routers');
@@ -207,11 +208,251 @@ describe('startServer', () => {
                 });
                 return {};
             },
-            middlewares: () => ({}),
+            middlewares: () => [],
             routers: () => { },
         });
         const app = await startServer(server);
         await app.close();
         expect(order).toEqual(['services', 'clients']);
     });
+    it('middlewares 按**数组顺序**注册（顺序即书写顺序，不受键名影响）', async () => {
+        const order = [];
+        const unit = (name) => ({ name, register: () => { order.push(name); } });
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({}),
+            // 故意用「纯数字会被对象重排」的反例命名，证明数组顺序不被引擎重排
+            middlewares: () => [unit('2-first'), unit('1-second'), unit('cors')],
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server);
+        expect(order).toEqual(['2-first', '1-second', 'cors']);
+        await app.close();
+    });
+    it('裸注册函数也能进数组（框架补占位名）', async () => {
+        let called = false;
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [() => { called = true; }],
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server);
+        expect(called).toBe(true);
+        await app.close();
+    });
+    it('clients 槽位可省略（CL 退化为空，services/middlewares/routers 照常）', async () => {
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => ({}),
+            // 不写 clients
+            services: () => ({}),
+            middlewares: () => [],
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server);
+        const res = await app.inject({ method: 'GET', url: '/probe' });
+        expect(res.statusCode).toBe(200);
+        await app.close();
+    });
+    it('env 扩展：手写首位泛型 Env 即可（defineServer<Env>({...})），值取内置加载后的 process.env（框架不提供自定义加载）', async () => {
+        const seen = {};
+        // 内置加载逻辑把它读进来；应用只在泛型上声明类型，不参与加载
+        process.env.SERVICE_TOKEN = 'from-process-env';
+        // Env 排泛型首位 → 可单独手写；ctx.env 随之带上 SERVICE_TOKEN 的类型
+        const server = defineServer({
+            app: IDENTITY,
+            resources: (ctx) => {
+                seen.fromResources = ctx.env.SERVICE_TOKEN;
+                return {};
+            },
+            config: (ctx) => {
+                // config 的 ctx.env 同样带上了扩展类型
+                seen.fromConfig = ctx.env.SERVICE_TOKEN;
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server);
+        expect(seen.fromResources).toBe('from-process-env');
+        expect(seen.fromConfig).toBe(seen.fromResources);
+        delete process.env.SERVICE_TOKEN;
+        await app.close();
+    });
+});
+describe('resources 单元生命周期（setup / dispose）', () => {
+    /** 造一个「记录调用」的资源单元 */
+    function probeResource(order, name, lifecycle = {}) {
+        const { setup = true, dispose = true } = lifecycle;
+        const client = { name };
+        return defineResource(client, {
+            ...(setup ? { setup: () => { order.push(`setup:${name}`); } } : {}),
+            ...(dispose ? { dispose: () => { order.push(`dispose:${name}`); } } : {}),
+        });
+    }
+    it('setup 在 resources 之后、config 之前，逐项按声明序执行', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => {
+                order.push('resources');
+                return { first: probeResource(order, 'first'), second: probeResource(order, 'second') };
+            },
+            config: () => {
+                order.push('config');
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        expect(order).toEqual(['resources', 'setup:first', 'setup:second', 'config']);
+        await app.close();
+    });
+    it('消费方拿到的是解包后的值，不是单元外壳', async () => {
+        const order = [];
+        let seen;
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({ database: probeResource(order, 'database') }),
+            config: (ctx) => {
+                seen = ctx.resources.database;
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        // 看到的是裸 client（`{ name: 'database' }`），没有 `value` / `setup` 外壳
+        expect(seen).toEqual({ name: 'database' });
+        await app.close();
+    });
+    it('裸对象（无单元外壳）照旧可用，不产生 setup / dispose 调用', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({ bare: { name: 'bare' } }),
+            config: () => ({ picked: true }),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        await app.close();
+        expect(order).toEqual([]);
+    });
+    it('setup 在每次装配时都跑（不做一次性记忆，迁移本身靠状态判定）', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({ database: probeResource(order, 'database', { dispose: false }) }),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const first = await startServer(server);
+        await first.close();
+        const second = await startServer(server);
+        await second.close();
+        expect(order).toEqual(['setup:database', 'setup:database']);
+    });
+    it('setup 抛错时装配中断（config 不跑），错误冒泡给入口', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({
+                database: defineResource({ name: 'database' }, {
+                    setup: () => {
+                        throw new Error('migrate failed');
+                    },
+                }),
+            }),
+            config: () => {
+                order.push('config');
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        await expect(startServer(server)).rejects.toThrow(/migrate failed/);
+        expect(order).toEqual([]);
+    });
+    it('dispose 按声明序**逆序**执行，排在 flushResources（disposer）之前', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: (ctx) => {
+                ctx.disposer.add(() => {
+                    order.push('disposer:resources');
+                });
+                return { first: probeResource(order, 'first'), second: probeResource(order, 'second') };
+            },
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        order.length = 0;
+        await app.close();
+        expect(order).toEqual(['dispose:second', 'dispose:first', 'disposer:resources']);
+    });
+    it('单个资源 dispose 失败不阻断其他资源（同阶段语义）', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({
+                broken: defineResource({ name: 'broken' }, {
+                    dispose: () => {
+                        throw new Error('disconnect failed');
+                    },
+                }),
+                healthy: probeResource(order, 'healthy', { setup: false }),
+            }),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        await expect(app.close()).resolves.toBeUndefined();
+        // 逆序：healthy 先于 broken；broken 抛错被吞，healthy 已经跑过
+        expect(order).toEqual(['dispose:healthy']);
+    });
+    it('出 spec 路径既不构造 resources，也不跑 setup', async () => {
+        const onSetup = vi.fn();
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({ database: defineResource({ name: 'database' }, { setup: onSetup }) }),
+            config: () => {
+                throw new Error('config 不应在出 spec 路径被调用');
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        await generateOpenApi(server);
+        expect(onSetup).not.toHaveBeenCalled();
+    });
 });

package/output/core/env.d.ts

@@ -1,5 +1,26 @@
 /** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
 export declare const DEFAULT_LOG_LEVEL = "info";
+/**
+ * 允许执行**破坏性 / 不可逆**操作的环境（`ENV` 取值）。
+ *
+ * 覆盖两类动作，两者共用同一份判定：
+ *
+ * - 测试数据库清理（`assertTestDatabaseSchema` 那道闸门的同伴）；
+ * - `testdata/` 脚本的 `load()` / `cleanup()`（`test-support/testdata.ts`）。
+ *
+ * `development` 是本地开发，`test` 是 vitest 入口显式声明的环境开关。除此之外一律拒绝——
+ * 只看 `NODE_ENV`、CI 标志或变量名都不构成证明：`NODE_ENV=test` 完全可能连着生产库。
+ */
+export declare const CLEANABLE_ENVS: readonly string[];
+/**
+ * 环境闸门：非可清理环境立即失败。
+ *
+ * **不在分支里「跳过清理」**——把破坏性动作降级成静默 no-op，会让同一份代码在生产和测试里
+ * 走两条不同的路径，测试结果随即失去意义。要禁就整体失败。
+ *
+ * 报错必须带上当前值：漏配 `ENV` 时的症状否则会变成「莫名其妙不许跑」。
+ */
+export declare function assertCleanableEnvironment(env: string): void;
 /**
  * 框架在配置前固定加载的 env（N2 §2.2）。
  *

package/output/core/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../source/core/env.ts"],"names":[],"mappings":"AAgCA,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,SAAS,CAAA;AA2BvC;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAA;IACX,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAA;IAChB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,IAAI,SAAS,CAQ5C;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,MAAM,CAAA;AAEhD,8BAA8B;AAC9B,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,eAAe,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,SAAS,CAY/E"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../source/core/env.ts"],"names":[],"mappings":"AAgCA,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,SAAS,CAAA;AAEvC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAA4B,CAAA;AAExE;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU5D;AA2BD;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAA;IACX,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAA;IAChB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,sDAAsD;AACtD,wBAAgB,gBAAgB,IAAI,SAAS,CAQ5C;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,MAAM,CAAA;AAEhD,8BAA8B;AAC9B,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,EAAE,eAAe,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,SAAS,CAY/E"}

package/output/core/env.js

@@ -29,6 +29,34 @@ const ENV_FILE_LAYERS = ['.env.dev', '.env', '.env.local'];
 const TEST_ENV_FILE_LAYERS = ['.env.test', '.env.test.local'];
 /** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
 export const DEFAULT_LOG_LEVEL = 'info';
+/**
+ * 允许执行**破坏性 / 不可逆**操作的环境（`ENV` 取值）。
+ *
+ * 覆盖两类动作，两者共用同一份判定：
+ *
+ * - 测试数据库清理（`assertTestDatabaseSchema` 那道闸门的同伴）；
+ * - `testdata/` 脚本的 `load()` / `cleanup()`（`test-support/testdata.ts`）。
+ *
+ * `development` 是本地开发，`test` 是 vitest 入口显式声明的环境开关。除此之外一律拒绝——
+ * 只看 `NODE_ENV`、CI 标志或变量名都不构成证明：`NODE_ENV=test` 完全可能连着生产库。
+ */
+export const CLEANABLE_ENVS = ['development', 'test'];
+/**
+ * 环境闸门：非可清理环境立即失败。
+ *
+ * **不在分支里「跳过清理」**——把破坏性动作降级成静默 no-op，会让同一份代码在生产和测试里
+ * 走两条不同的路径，测试结果随即失去意义。要禁就整体失败。
+ *
+ * 报错必须带上当前值：漏配 `ENV` 时的症状否则会变成「莫名其妙不许跑」。
+ */
+export function assertCleanableEnvironment(env) {
+    if (CLEANABLE_ENVS.includes(env)) {
+        return;
+    }
+    throw new Error(`[env-gate] 拒绝在 ENV="${env || '<未设置>'}" 下执行会清理数据的操作：` +
+        `只接受 ${CLEANABLE_ENVS.join(' / ')}。` +
+        '会写入 / 清理 / truncate / reset 数据库的操作绝不能指向非开发环境。');
+}
 /**
  * 首次 import 时的真实环境变量快照（此时还没有任何 .env 文件被加载）。
  * 加载结束后原样恢复，实现「外部注入 > .env.local > .env > .env.dev」。

package/output/core/resource.d.ts

@@ -0,0 +1,56 @@
+import type { ResourceLifecycle, ResourceUnit } from './types.js';
+/**
+ * 构造资源单元（唯一的正当方式）。
+ *
+ * ## 为什么需要外壳
+ *
+ * 资源多是**第三方对象**：`PrismaClient`、Redis client、HTTP 连接池⋯⋯它们的形状改不了。
+ * service 可以直接在对象上挂 `init()`（因为 service 是本仓自己写的），资源不行——
+ * `prisma.setup = …` 是在改别人的类型，运行期也未必允许。
+ *
+ * 所以 `setup()` 挂在**框架私有外壳**上，`value` 原样保留：
+ *
+ * ```ts
+ * resources: (ctx) => ({
+ *   database: defineResource(createPrisma(ctx.env.DATABASE_URL), {
+ *     async setup() { await pushSchema(ctx.env.DATABASE_URL) },
+ *   }),
+ * })
+ * ```
+ *
+ * 消费方读 `ctx.resources.database` 拿到的是 `PrismaClient` 本身
+ * （`ResourcesView` 会解包），不是 `ResourceUnit<PrismaClient>`。
+ *
+ * ## 单元是可选的
+ *
+ * 裸对象照旧可用（无 `setup`、无解包开销）：`resources: () => ({ database: prisma })`。
+ * 只有需要「装配期准备」的资源才包一层。
+ *
+ * ## `setup` 何时跑、谁跑
+ *
+ * - **何时**：`resources` 槽位构造完成后、`config` 槽位之前；按**对象声明序**逐项 `await`。
+ *   排在 `config` 前是硬要求——`config` 常从数据库读（如 `SystemConfig` 表），库没准备好
+ *   它就连不上。
+ * - **谁**：框架。`startServer` / `createTestServer` 都调；`generateOpenApi` 不调
+ *   （出 spec 不构造资源）。应用**永不手调**。
+ * - **失败**：立即中断装配并把错误抛给入口（已构造的资源照常释放）。资源准备失败后
+ *   `config` / `services` 都没有意义，所以不吞。
+ *
+ * ## 不要在里面写 `if (ENV === 'test')`
+ *
+ * 准备动作本身应当是**状态驱动**的：`prisma db push` / `migrate deploy` 都会自己比对现状、
+ * 只补差量，生产与测试跑同一份代码。需要区分环境的细节应当从 `ctx.env` 取，而不是让
+ * 「跑不跑这个函数」变成环境分支。
+ *
+ * ## 用例间重置不在本文件
+ *
+ * 「清表 / 清缓存 / 重新插入样本数据」不适合挂在资源上：资源只知道有哪些表、哪些 key，
+ * 不知道**谁往里写了什么**。写在资源上就变成了「新增一个 model 就得回去改一次清库清单」，
+ * 漏改只会安静地变脏。
+ *
+ * 所以它单独成机制：**`packages/server/testdata/*.ts|js`，每个脚本自带 `load()` / `cleanup()`**，
+ * 由框架在 `development` / `test` 下自动装载并执行（见 `core/test-support/testdata.ts`）。
+ * 数据脚本自己知道要插入什么，也就自己知道怎么删干净。
+ */
+export declare function defineResource<Value>(value: Value, lifecycle?: ResourceLifecycle): ResourceUnit<Value>;
+//# sourceMappingURL=resource.d.ts.map

package/output/core/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../source/core/resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,iBAAiB,GAAG,YAAY,CAAC,KAAK,CAAC,CAEtG"}