@taicode/common-server 4.0.0-beta.2 → 4.0.0-beta.4

package/output/core/entries.test.js

@@ -0,0 +1,217 @@
+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';
+const IDENTITY = { service: 'probe', title: 'Probe', version: '0.0.0' };
+const ROUTE_SCHEMA = routerSchema({
+    operationId: 'probeGet',
+    summary: '探测',
+    description: '探测路由',
+    tags: ['探测'],
+});
+/**
+ * 出 spec 用的定义：`config` 工厂**故意抛错**、`middlewares` 工厂记调用次数。
+ *
+ * 两者都能跑通就证明：出 spec 路径**既不需要配置有效**，**也不装配任何中间件**
+ * （它的文档只取决于路由声明 + zod 转换）。
+ */
+function buildServer(registerPermissionOperations, onMiddlewares = vi.fn()) {
+    return defineServer({
+        app: IDENTITY,
+        resources: () => ({}),
+        config: () => {
+            throw new Error('config 不应在出 spec 路径被调用');
+        },
+        clients: () => ({}),
+        services: () => ({}),
+        middlewares: (ctx) => {
+            onMiddlewares();
+            return {
+                auth: createAuthMiddleware(ctx, {
+                    client: { verify: async () => ({ user: {}, token: 't' }), registerPermissionOperations },
+                }),
+            };
+        },
+        routers: ({ app }) => {
+            app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+        },
+    });
+}
+/** 启动用的定义：`config` 正常返回值（`startServer` 会跑它）。 */
+function buildStartableServer(registerPermissionOperations) {
+    return defineServer({
+        app: IDENTITY,
+        resources: () => ({}),
+        config: () => ({ server: { cookieNames: ['token'] } }),
+        clients: () => ({}),
+        services: () => ({}),
+        middlewares: (ctx) => ({
+            auth: createAuthMiddleware(ctx, {
+                client: { verify: async () => ({ user: {}, token: 't' }), registerPermissionOperations },
+            }),
+        }),
+        routers: ({ app }) => {
+            app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+        },
+    });
+}
+describe('generateOpenApi', () => {
+    it('产出完整文档（含框架系统路由与业务路由）', async () => {
+        const spec = await generateOpenApi(buildServer(async () => { }));
+        expect(Object.keys(spec.paths ?? {})).toEqual(expect.arrayContaining(['/', '/health', '/system/openapi', '/system/info', '/probe']));
+        expect(spec.info).toEqual({ title: 'Probe', version: '0.0.0' });
+        expect(spec.openapi).toBe('3.0.3');
+    });
+    it('不向鉴权提供方提交权限目录（构建期不产生写操作）', async () => {
+        const registerPermissionOperations = vi.fn(async () => { });
+        await generateOpenApi(buildServer(registerPermissionOperations));
+        expect(registerPermissionOperations).not.toHaveBeenCalled();
+    });
+    it('不装配中间件（文档只取决于路由声明，副作用随之消失）', async () => {
+        const onMiddlewares = vi.fn();
+        await generateOpenApi(buildServer(async () => { }, onMiddlewares));
+        // `auth` 单元在出文档路径里压根不会被构造——这是「不向鉴权方写数据」的根因，
+        // 而不是靠某个入口标记把它关掉。
+        expect(onMiddlewares).not.toHaveBeenCalled();
+    });
+    it('不构造 resources / config / clients / services（文档不来自它们，构造它们只为了跑服务）', async () => {
+        const onResources = vi.fn();
+        const onServices = vi.fn();
+        const onClients = vi.fn();
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => {
+                onResources();
+                return {};
+            },
+            config: () => {
+                throw new Error('config 不应在出 spec 路径被调用');
+            },
+            clients: () => {
+                onClients();
+                return {};
+            },
+            services: () => {
+                onServices();
+                return {};
+            },
+            middlewares: () => ({}),
+            routers: ({ app }) => {
+                app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const spec = await generateOpenApi(server);
+        expect(onResources).not.toHaveBeenCalled();
+        expect(onClients).not.toHaveBeenCalled();
+        expect(onServices).not.toHaveBeenCalled();
+        // 传的是空 services 占位，路由仍能正常注册并进入文档
+        expect(Object.keys(spec.paths ?? {})).toContain('/probe');
+    });
+    it('不跑 config 槽位（出 spec 不要求配置有效）', async () => {
+        // `config` 工厂本身就会抛错，能出 spec 即证明它没被调用
+        await expect(generateOpenApi(buildServer(async () => { }))).resolves.toBeDefined();
+    });
+    it('不监听端口（不占用 API_PORT）', async () => {
+        const spec = await generateOpenApi(buildServer(async () => { }));
+        expect(spec.servers).toEqual([{ url: '/' }]);
+    });
+    it('业务路由违反 schema 契约时出 spec 直接失败（不给漏声明留活路）', async () => {
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => ({}),
+            clients: () => ({}),
+            services: () => ({}),
+            middlewares: () => ({}),
+            routers: ({ app }) => {
+                // 故意不声明 schema，验证运行期守卫
+                app.get('/bad', async () => ({ ok: true }));
+            },
+        });
+        await expect(generateOpenApi(server)).rejects.toThrow(/GET \/bad 缺少 schema/);
+    });
+});
+describe('startServer', () => {
+    // 入口一定 listen，所以这里要一个合法端口：`0` 让内核分配空闲端口，测试不抢固定端口
+    beforeAll(() => {
+        process.env.API_PORT = '0';
+    });
+    it('运行期照常提交权限目录（与出 spec 入口相反）', async () => {
+        const registerPermissionOperations = vi.fn(async () => { });
+        const app = await startServer(buildStartableServer(registerPermissionOperations));
+        // `startServer` 的契约就是「一定 listen」：端口交给内核分配（`API_PORT=0`），不靠开关
+        expect(app.server.listening).toBe(true);
+        // startServer 内部已 `ready()`，钩子应在返回前执行完
+        expect(registerPermissionOperations).toHaveBeenCalledTimes(1);
+        const [payload] = registerPermissionOperations.mock.calls[0];
+        expect(payload.service).toBe('probe');
+        expect(payload.version).toBe('0.0.0');
+        expect(payload.operations.map((item) => item.operation)).toEqual(expect.arrayContaining(['probeGet', 'getOpenApiDocument']));
+        await app.close();
+    });
+    it('clients 在 config 之后、services 之前构造，并被 services / middlewares / routers 共享同一实例', async () => {
+        const order = [];
+        const seen = {};
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => {
+                order.push('config');
+                return { account: { serviceUrl: 'https://account.invalid' } };
+            },
+            clients: (ctx) => {
+                order.push('clients');
+                // 客户端地址来自业务配置（不是 env）——这正是它不能放进 resources 的原因
+                return { account: { baseUrl: ctx.config.account.serviceUrl } };
+            },
+            services: (ctx) => {
+                order.push('services');
+                // 两个 service 拿到的是**同一份**客户端实例：services 之间禁止互依，只能靠这一层共享
+                seen.serviceFirst = ctx.clients.account;
+                seen.serviceSecond = ctx.clients.account;
+                return {};
+            },
+            middlewares: (ctx) => {
+                seen.middleware = ctx.clients.account;
+                return {};
+            },
+            routers: (ctx) => {
+                order.push('routers');
+                seen.router = ctx.clients.account;
+                ctx.app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
+            },
+        });
+        const app = await startServer(server);
+        expect(order).toEqual(['config', 'clients', 'services', 'routers']);
+        expect(seen.serviceFirst).toEqual({ baseUrl: 'https://account.invalid' });
+        expect(seen.serviceSecond).toBe(seen.serviceFirst);
+        expect(seen.middleware).toBe(seen.serviceFirst);
+        expect(seen.router).toBe(seen.serviceFirst);
+        await app.close();
+    });
+    it('clients 阶段在 services 之后关闭（服务 dispose 时外部客户端仍可用）', async () => {
+        const order = [];
+        const server = defineServer({
+            app: IDENTITY,
+            resources: () => ({}),
+            config: () => ({}),
+            clients: (ctx) => {
+                ctx.disposer.add(() => {
+                    order.push('clients');
+                });
+                return {};
+            },
+            services: (ctx) => {
+                ctx.disposer.add(() => {
+                    order.push('services');
+                });
+                return {};
+            },
+            middlewares: () => ({}),
+            routers: () => { },
+        });
+        const app = await startServer(server);
+        await app.close();
+        expect(order).toEqual(['services', 'clients']);
+    });
+});

package/output/core/env.d.ts

@@ -0,0 +1,62 @@
+/** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
+export declare const DEFAULT_LOG_LEVEL = "info";
+/**
+ * 框架在配置前固定加载的 env（N2 §2.2）。
+ *
+ * 只读固定约定值：`ENV` / `API_PORT` / `LOG_LEVEL` / `DATABASE_URL` / `REDIS_URL`；
+ * `debug` 由 `ENV === 'development'` 派生；**绝不回退 `PORT`**（`PORT` 属 nginx）。
+ *
+ * **不给索引签名**：访问 `env.XXX` 拼错即编译错误。各仓若有额外 env，不扩展这个类型 ——
+ * 走 `process.env.XXX`（在 `resources(ctx)` 里读），框架不背书。
+ */
+export interface ConfigEnv {
+    /** 运行环境标记；`debug` 由 `ENV === 'development'` 派生 */
+    ENV: string;
+    /** 监听端口；**只读 `API_PORT`，绝不回退 `PORT`** */
+    API_PORT: string;
+    /** 日志级别；默认 `info` */
+    LOG_LEVEL: string;
+    /** 数据层连接串（`resources` 只读它构造数据层客户端） */
+    DATABASE_URL: string;
+    /** Redis 连接串；缺省 → redis 资源为 `undefined` */
+    REDIS_URL?: string;
+}
+/** 读取固定 env（不加载文件）；入口会先 `loadEnvironment()` 再调用本函数 */
+export declare function resolveConfigEnv(): ConfigEnv;
+/**
+ * env 加载模式：
+ *
+ * - `runtime`（默认）`startServer` 与工具进程用：三层开发分层，`ENV=test` 时再叠测试层。
+ * - `test` 测试入口用：**无条件**叠测试层，且三/五层都没给出 `ENV` 时兜底成 `test`。
+ */
+export type EnvironmentMode = 'runtime' | 'test';
+/** `loadEnvironment()` 的选项 */
+export interface LoadEnvironmentOptions {
+    mode?: EnvironmentMode;
+}
+/**
+ * 加载 env 文件并在加载后返回固定约定值。
+ *
+ * **这是 env 的唯一出口**：层名、顺序、覆盖规则全在框架内部，业务与工具进程只表达
+ * 「我要运行期 env」还是「我要测试 env」（`mode: 'test'`），不接触 `.env.dev` /
+ * `.env.test.local` 这些文件名。
+ *
+ * 三种调用方：
+ *
+ * - `startServer`：`loadEnvironment()`（最早阶段固定调用）；
+ * - `createTestServer`：经 `prepareTestDatabase()` 间接调用（再跑两道闸门）；
+ * - 工具进程（`vitest.config.ts` / `prisma.config.ts` / `scripts/*.ts`）：调
+ *   `loadRuntimeEnvironment()`（它只是本函数的具名包装）—— 它们不被任何入口覆盖。
+ *
+ * `mode: 'test'` 的语义顺序：
+ *
+ * 1. 先加载三层开发分层，再叠测试层（两套 .env.test 逐层覆盖）；
+ * 2. `loadLayers` 末尾把**外部注入**（进程 / 容器 / CI）原样恢复 —— 所以线上注入的
+ *    `ENV=production` 一定压过仓库里的 `.env.test`，随后的环境闸门照旧拒绕启动；
+ * 3. 前面都没给出 `ENV` 时才兜底成 `test`：测试入口的默认身份就是测试，不该要求调用方
+ *    额外声明一次（否则漏写就变成「环境必须是 development/test」的莫名报错）。
+ *
+ * `generateOpenApi` **不**调用本函数（它不要求配置有效，设计 §3.2 规则 A/B）。
+ */
+export declare function loadEnvironment(options?: LoadEnvironmentOptions): ConfigEnv;
+//# sourceMappingURL=env.d.ts.map

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

@@ -0,0 +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"}

package/output/core/env.js

@@ -0,0 +1,96 @@
+import { config } from 'dotenv';
+/**
+ * 默认 env 文件分层（低 → 高优先级，后者覆盖前者）：
+ *
+ *   .env.dev   已提交进仓库的 dev 默认值（克隆后 `pnpm run dev` 开箱即用）
+ *   .env       本机私有覆盖（已被 gitignore）
+ *   .env.local 本机更高优先级覆盖（已被 gitignore）
+ *
+ * 真实环境变量（进程/容器注入）优先级最高，任何 .env 文件都不会覆盖它们 —— 这条保证让 CI、
+ * helm、`docker run -e` 等显式注入始终生效，也避免测试探针
+ * （`check-test-database-isolation`）注入的连接串被仓库里的默认值顶掉。
+ *
+ * 解析器与四家现状保持一致，统一使用 `dotenv`，以保证多行值、引号/转义、`export` 前缀等
+ * 细节语义完全等价（设计 §3.1 ①：与现状逐字一致）。
+ *
+ * **分层是框架的内部实现**：不导出、不参数化。调用方只表达「我要运行期 env」还是「我要测试
+ * env」（`mode`），层名与顺序不进入业务代码。
+ */
+const ENV_FILE_LAYERS = ['.env.dev', '.env', '.env.local'];
+/**
+ * 测试层（叠在 `ENV_FILE_LAYERS` 之上，低 → 高）：
+ *
+ *   .env.test       测试环境默认值（可提交：`ENV=test`、测试库连接串）
+ *   .env.test.local 本机覆盖（已被 gitignore）
+ *
+ * 测试入口**无条件**加载这两层（不等 `ENV === 'test'`）：测试入口的存在本身就意味着「这是
+ * 测试」，让调用方再声明一次是多余且容易漏的。
+ */
+const TEST_ENV_FILE_LAYERS = ['.env.test', '.env.test.local'];
+/** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
+export const DEFAULT_LOG_LEVEL = 'info';
+/**
+ * 首次 import 时的真实环境变量快照（此时还没有任何 .env 文件被加载）。
+ * 加载结束后原样恢复，实现「外部注入 > .env.local > .env > .env.dev」。
+ */
+const EXTERNAL_ENV = new Map(Object.entries(process.env).filter((entry) => entry[1] !== undefined));
+/**
+ * 按分层顺序加载 env 文件（内部实现，见上方「分层不导出」的约定）。
+ *
+ * @param extraLayers 追加在最高优先级的额外层
+ */
+function loadLayers(extraLayers = []) {
+    const layers = [...ENV_FILE_LAYERS, ...extraLayers];
+    layers.forEach((path, index) => {
+        // 第一层不覆盖已有值，后续层逐层覆盖前一层
+        config({ path, override: index > 0 });
+    });
+    for (const [key, value] of EXTERNAL_ENV) {
+        process.env[key] = value;
+    }
+}
+/** 读取固定 env（不加载文件）；入口会先 `loadEnvironment()` 再调用本函数 */
+export function resolveConfigEnv() {
+    return {
+        ENV: process.env.ENV ?? '',
+        API_PORT: process.env.API_PORT ?? '',
+        LOG_LEVEL: process.env.LOG_LEVEL ?? DEFAULT_LOG_LEVEL,
+        DATABASE_URL: process.env.DATABASE_URL ?? '',
+        REDIS_URL: process.env.REDIS_URL,
+    };
+}
+/**
+ * 加载 env 文件并在加载后返回固定约定值。
+ *
+ * **这是 env 的唯一出口**：层名、顺序、覆盖规则全在框架内部，业务与工具进程只表达
+ * 「我要运行期 env」还是「我要测试 env」（`mode: 'test'`），不接触 `.env.dev` /
+ * `.env.test.local` 这些文件名。
+ *
+ * 三种调用方：
+ *
+ * - `startServer`：`loadEnvironment()`（最早阶段固定调用）；
+ * - `createTestServer`：经 `prepareTestDatabase()` 间接调用（再跑两道闸门）；
+ * - 工具进程（`vitest.config.ts` / `prisma.config.ts` / `scripts/*.ts`）：调
+ *   `loadRuntimeEnvironment()`（它只是本函数的具名包装）—— 它们不被任何入口覆盖。
+ *
+ * `mode: 'test'` 的语义顺序：
+ *
+ * 1. 先加载三层开发分层，再叠测试层（两套 .env.test 逐层覆盖）；
+ * 2. `loadLayers` 末尾把**外部注入**（进程 / 容器 / CI）原样恢复 —— 所以线上注入的
+ *    `ENV=production` 一定压过仓库里的 `.env.test`，随后的环境闸门照旧拒绕启动；
+ * 3. 前面都没给出 `ENV` 时才兜底成 `test`：测试入口的默认身份就是测试，不该要求调用方
+ *    额外声明一次（否则漏写就变成「环境必须是 development/test」的莫名报错）。
+ *
+ * `generateOpenApi` **不**调用本函数（它不要求配置有效，设计 §3.2 规则 A/B）。
+ */
+export function loadEnvironment(options = {}) {
+    const test = options.mode === 'test';
+    loadLayers(test ? TEST_ENV_FILE_LAYERS : undefined);
+    if (!test && (process.env.ENV ?? '') === 'test') {
+        loadLayers(TEST_ENV_FILE_LAYERS);
+    }
+    if (test && (process.env.ENV ?? '') === '') {
+        process.env.ENV = 'test';
+    }
+    return resolveConfigEnv();
+}

package/output/{app → core}/env.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.test.d.ts","sourceRoot":"","sources":["../../source/app/env.test.ts"],"names":[],"mappings":""}
+{"version":3,"file":"env.test.d.ts","sourceRoot":"","sources":["../../source/core/env.test.ts"],"names":[],"mappings":""}

package/output/core/env.test.js

@@ -0,0 +1,105 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { loadEnvironment } from './env.js';
+const ORIGINAL_ENV = { ...process.env };
+const ORIGINAL_CWD = process.cwd();
+const TEMP_ROOTS = [];
+afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    process.chdir(ORIGINAL_CWD);
+    for (const root of TEMP_ROOTS.splice(0)) {
+        rmSync(root, { recursive: true, force: true });
+    }
+    vi.resetModules();
+});
+/** 在临时目录里起一个项目根并写文件，然后切过去（`dotenv` 按 `process.cwd()` 解析相对路径） */
+function useTempProject(files) {
+    const root = mkdtempSync(join(tmpdir(), 'common-env-'));
+    TEMP_ROOTS.push(root);
+    for (const [name, content] of Object.entries(files)) {
+        writeFileSync(join(root, name), content);
+    }
+    process.chdir(root);
+}
+describe('loadEnvironment · runtime（工具进程 / startServer）', () => {
+    it('加载 .env.dev / .env / .env.local 三层，且逐层覆盖', () => {
+        useTempProject({
+            '.env.dev': 'PROBE_LAYER=dev\nPROBE_DEV_ONLY=yes\n',
+            '.env': 'PROBE_LAYER=env\n',
+            '.env.local': 'PROBE_LAYER=local\n',
+        });
+        delete process.env.PROBE_LAYER;
+        delete process.env.PROBE_DEV_ONLY;
+        loadEnvironment();
+        expect(process.env.PROBE_LAYER).toBe('local');
+        expect(process.env.PROBE_DEV_ONLY).toBe('yes');
+    });
+    it('不加载测试层（ENV 不是 test 时）', () => {
+        useTempProject({ '.env.test': 'PROBE_TEST_ONLY=yes\n' });
+        process.env.ENV = 'development';
+        delete process.env.PROBE_TEST_ONLY;
+        loadEnvironment();
+        expect(process.env.PROBE_TEST_ONLY).toBeUndefined();
+    });
+    it('ENV=test 时追加测试层', () => {
+        useTempProject({ '.env.test': 'PROBE_TEST_ONLY=yes\n' });
+        process.env.ENV = 'test';
+        delete process.env.PROBE_TEST_ONLY;
+        loadEnvironment();
+        expect(process.env.PROBE_TEST_ONLY).toBe('yes');
+    });
+    it('不给 ENV 时不兜底（运行期必须有明确身份）', () => {
+        useTempProject({});
+        delete process.env.ENV;
+        expect(loadEnvironment().ENV).toBe('');
+    });
+});
+describe('loadEnvironment · test（测试入口）', () => {
+    it('无条件加载测试层，不需要调用方先声明 ENV=test', () => {
+        useTempProject({ '.env.test': 'PROBE_TEST_ONLY=yes\n' });
+        process.env.ENV = 'development';
+        delete process.env.PROBE_TEST_ONLY;
+        loadEnvironment({ mode: 'test' });
+        expect(process.env.PROBE_TEST_ONLY).toBe('yes');
+    });
+    it('.env.test.local 覆盖 .env.test', () => {
+        useTempProject({
+            '.env.test': 'PROBE_LAYER=from-test\n',
+            '.env.test.local': 'PROBE_LAYER=from-local\n',
+        });
+        delete process.env.PROBE_LAYER;
+        loadEnvironment({ mode: 'test' });
+        expect(process.env.PROBE_LAYER).toBe('from-local');
+    });
+    it('没有任何 ENV 时兜底成 test', () => {
+        useTempProject({});
+        delete process.env.ENV;
+        expect(loadEnvironment({ mode: 'test' }).ENV).toBe('test');
+    });
+    it('已声明 ENV 时不被兜底改写', () => {
+        useTempProject({});
+        process.env.ENV = 'development';
+        expect(loadEnvironment({ mode: 'test' }).ENV).toBe('development');
+    });
+});
+describe('外部注入优先级（两种模式都必须成立）', () => {
+    it('runtime：.env 不覆盖进程已注入的值', async () => {
+        useTempProject({ '.env': 'PROBE_LAYER=from-file\n' });
+        // 同上：外部注入的快照在模块 import 时建立，重新 import 才能模拟真实注入时机
+        vi.resetModules();
+        process.env.PROBE_LAYER = 'from-process';
+        const fresh = await import('./env.js');
+        fresh.loadEnvironment();
+        expect(process.env.PROBE_LAYER).toBe('from-process');
+    });
+    it('test：线上注入的 ENV=production 不被 .env.test 顶掉（环境闸门因此仍会拒绝）', async () => {
+        useTempProject({ '.env.test': 'ENV=test\n' });
+        // EXTERNAL_ENV 是模块首次 import 时的快照，重新 import 才能模拟「进程启动前注入」
+        vi.resetModules();
+        process.env.ENV = 'production';
+        const fresh = await import('./env.js');
+        expect(fresh.loadEnvironment({ mode: 'test' }).ENV).toBe('production');
+    });
+});

package/output/core/modules/auth-provider/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `core/modules/auth-provider` 的出口：**只有类型，没有实现、没有地址**。
+ *
+ * 实现由业务服务提供（`createAuthMiddleware({ client })`）：框架不建 HTTP 客户端、
+ * 不认任何地址、不做签名、不管超时——见 `types.ts` 文件头与设计 §5.2.2。
+ *
+ * 提供方是**可替换**的：account 只是当前的主要实现，不是框架的预设。
+ */
+export type { AuthClient, AuthVerifyMetadata, AuthVerifyPayload, AuthVerifyResult, RegisterPermissionOperationsPayload, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/output/core/modules/auth-provider/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/auth-provider/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,mCAAmC,GACpC,MAAM,YAAY,CAAA"}

package/output/core/modules/auth-provider/index.js

@@ -0,0 +1,9 @@
+/**
+ * `core/modules/auth-provider` 的出口：**只有类型，没有实现、没有地址**。
+ *
+ * 实现由业务服务提供（`createAuthMiddleware({ client })`）：框架不建 HTTP 客户端、
+ * 不认任何地址、不做签名、不管超时——见 `types.ts` 文件头与设计 §5.2.2。
+ *
+ * 提供方是**可替换**的：account 只是当前的主要实现，不是框架的预设。
+ */
+export {};

package/output/core/modules/auth-provider/types.d.ts

@@ -0,0 +1,71 @@
+import type { PermissionOperation } from '../permission-operations/index.js';
+import type { AccessControl } from '../../type-augment.js';
+/**
+ * core `auth-provider` 集成层：**只有最小接口约束，没有实现、没有地址**。
+ *
+ * 鉴权提供方（Auth Provider）是**可替换**的——account 只是当前的主要实现之一，
+ * 任何能「校验凭证 + 接收权限目录」的系统都可以填进来（自建 IAM、OIDC 网关、
+ * 单点登录服务、甚至进程内的静态校验）。
+ *
+ * 为什么只留契约（设计 §5.2.2）：
+ *
+ * - 客户端的**构造**依赖业务侧才知道的东西——`serviceUrl`（来自配置 / 服务发现 /
+ *   私有网络）、端点路径（属于提供方的业务契约，不在 framework）、服务凭证、
+ *   以及项目自己的 `fetch` / 拦截器 / 超时 / 重试策略。框架猜不出来，也不该猜。
+ * - 所以框架只声明「**调用鉴权提供方需要什么形状**」，由每个服务在自己 `config` /
+ *   `resources` 槽位里实现 `AuthClient`，注入给 `auth` 的 `client` 选项。
+ *
+ * 契约本身是冻结的（框架只用到两个能力：校验凭证、注册权限操作）：改形状等于改契约。
+ * **地址与路径不进 framework**——它们随部署环境变化，属于业务配置。
+ */
+/** 校验请求附带的请求元信息（仅供下游审计 / 日志；不参与鉴权判定） */
+export interface AuthVerifyMetadata {
+    ip?: string;
+    ips?: string[];
+    url?: string;
+    method?: string;
+    referrer?: string;
+    requestId?: string;
+    userAgent?: string;
+}
+/** `verify` 的请求体：调鉴权提供方的校验能力时提交什么 */
+export interface AuthVerifyPayload {
+    token?: string;
+    apiKey?: string;
+    /** 调用方服务名（`AppIdentity.service`） */
+    service: string;
+    /** 操作标识（路由 `schema.operationId`，缺省回落 url） */
+    operation?: string;
+    /** 路由参数（`request.params`），如 `:id` 这类路径参数 */
+    resource?: Record<string, unknown>;
+    accessControls?: AccessControl[];
+    metadata?: AuthVerifyMetadata;
+}
+/** `verify` 的响应数据 */
+export interface AuthVerifyResult {
+    user?: unknown;
+    token?: unknown;
+}
+/** 权限操作自注册的请求体：调鉴权提供方的权限目录端点时提交什么 */
+export interface RegisterPermissionOperationsPayload {
+    service: string;
+    version: string;
+    operations: PermissionOperation[];
+}
+/**
+ * 鉴权客户端契约：框架只需要**两个**方法。
+ *
+ * 实现归业务服务（`createAuthMiddleware` 的 `client` 选项）：**URL / 路径 / 签名 /
+ * 协议（HTTP、gRPC、进程内调用）/ 超时 / 重试全在业务侧**，框架不认识任何地址。
+ * account 只是其中一种实现，不是唯一一种。
+ *
+ * 失败语义：
+ * - `verify` 抛错 = 校验不通过或提供方不可用；提供方应**自己抛** `UserError` /
+ *   `SystemError`（框架原样透出），其余错误统一归类为 `EXTERNAL_SERVICE_ERROR`；
+ * - `registerPermissionOperations` 抛错**不致命**（`auth` 只记日志，不中断启动）。
+ */
+export interface AuthClient {
+    verify(payload: AuthVerifyPayload): Promise<AuthVerifyResult>;
+    registerPermissionOperations(payload: RegisterPermissionOperationsPayload): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/output/core/modules/auth-provider/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/auth-provider/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D;;;;;;;;;;;;;;;;;GAiBG;AAEH,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,MAAM,EAAE,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAA;IACf,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,cAAc,CAAC,EAAE,aAAa,EAAE,CAAA;IAChC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;CAC9B;AAED,qBAAqB;AACrB,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,qCAAqC;AACrC,MAAM,WAAW,mCAAmC;IAClD,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,mBAAmB,EAAE,CAAA;CAClC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC7D,4BAA4B,CAAC,OAAO,EAAE,mCAAmC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1F"}

package/output/core/modules/context/index.d.ts

@@ -0,0 +1,18 @@
+import type { FastifyBaseLogger, FastifyInstance, FastifyRequest } from 'fastify';
+/**
+ * core `context`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * 两部分：
+ * 1. `RequestContext` / `createContext`：请求级上下文的形状与构造；
+ * 2. `registerRequestContext`：把上下文装配到 `request.ctx`（`decorateRequest` + `onRequest`）。
+ *
+ * `request.ctx` 是 `type-augment` 对外承诺的类型契约，装配必须由框架保证——不能交由
+ * 各仓决定「装不装 / 装成什么名字」，否则类型存在而运行时缺失。装饰名固定 `ctx`，无选项。
+ */
+export interface RequestContext {
+    log: FastifyBaseLogger;
+}
+export declare function createContext(request: FastifyRequest): RequestContext;
+/** 装配 `request.ctx`（框架固定，先于任何路由 / 业务中间件注册） */
+export declare function registerRequestContext(app: FastifyInstance): void;
+//# sourceMappingURL=index.d.ts.map

package/output/core/modules/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEjF;;;;;;;;;GASG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,iBAAiB,CAAA;CACvB;AAcD,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAErE;AAED,8CAA8C;AAC9C,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAOjE"}

package/output/core/modules/context/index.js

@@ -0,0 +1,23 @@
+const fallbackLogger = {
+    trace: () => { },
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+    fatal: () => { },
+    child: () => fallbackLogger,
+    level: 'info',
+    silent: () => { },
+};
+export function createContext(request) {
+    return { log: request.log || fallbackLogger };
+}
+/** 装配 `request.ctx`（框架固定，先于任何路由 / 业务中间件注册） */
+export function registerRequestContext(app) {
+    // 先声明属性（保持 hidden class 稳定），再在 `onRequest` 逐个请求写入
+    app.decorateRequest('ctx', null);
+    app.addHook('onRequest', (request, _reply, done) => {
+        request.ctx = createContext(request);
+        done();
+    });
+}

package/output/core/modules/context/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/context/index.test.ts"],"names":[],"mappings":""}