@taicode/common-server 4.0.0-beta.1 → 4.0.0-beta.10

package/output/core/test-support/database.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 测试数据库安全检查（强制规则见 `@taicode/skills` 的 `test-database-isolation`）。
+ *
+ * 两道闸门，缺一不可：
+ *
+ * | 闸门 | 拒绝条件 | 缺失后的后果 |
+ * | --- | --- | --- |
+ * | 环境闸门 | `ENV` 不是可清理环境 | 生产 runner 上误跑破坏性测试 |
+ * | schema 闸门 | 目标 schema 不以 `_test` 结尾 | 绕过命名约定后仍能同步 / 清理应用 schema |
+ *
+ * 不需要「应用目标 vs 测试目标」比对：测试目标只由 `DATABASE_URL` **派生**得到（schema
+ * 追加 `_test`，幂等），再由 schema 闸门只放行 `*_test`。两条合起来，测试目标结构上不可能
+ * 是应用目标；再拿两个连接串互相比较，比的也只是同一份派生结果。
+ *
+ * ## 为什么在框架里
+ *
+ * 这套逻辑此前在 `account` / `expense` / `release` / `observai` 各写一遍，互相抄、互相漂移。
+ * 它保护的是**数据不丢**，属于「项目可以决定怎么实现，但不能决定要不要实现」的那类规则——
+ * 所以实现只能有一份，由框架提供；各仓的 `vitest.config.ts` / `global-setup.ts` 只调用，不复制。
+ *
+ * ## 为什么用 `throw` 而不是 `process.exit`
+ *
+ * 本模块被两类进程共用：
+ *
+ * - `createTestServer`（vitest worker 内）：退出码由 vitest 决定，抛错即该文件失败；
+ * - `vitest.config.ts` / `global-setup.ts`（配置与全局初始化）：抛错同样以非零状态结束进程。
+ *
+ * 抛错在两处都能得到「立刻失败」，而 `process.exit(1)` 在 worker 内会杀掉整个进程池、
+ * 丢掉其余文件的报告。错误信息本身必须足够定位，不能靠退出码表达。
+ */
+/** 测试 schema 的强制后缀（`account` → `account_test`） */
+export declare const TEST_SCHEMA_SUFFIX = "_test";
+/**
+ * 一个连接串的**全部**连接维度。
+ *
+ * 比较必须覆盖四个维度：只比字符串会误判（`localhost:5432` 与 `localhost:5432/` 不同、
+ * `?schema=` 与默认端口都能让「不同字符串」指向同一 schema）。
+ */
+export interface DatabaseTarget {
+    hostname: string;
+    /** 已按默认端口补齐 */
+    port: string;
+    /** 路径部分（不含开头的 `/`） */
+    database: string;
+    /** `?schema=`，缺省 `public` */
+    schema: string;
+}
+/** 解析连接串的连接维度（解析失败即抛错：配置错误不该被当成「不同的目标」放过去） */
+export declare function resolveDatabaseTarget(connectionString: string): DatabaseTarget;
+/**
+ * 打印用的连接串（**密码一律替换为 `***`**）。
+ *
+ * 报错要能定位「连的是哪儿」，但不能把密码写进 CI 日志。
+ */
+export declare function maskDatabaseUrl(connectionString: string): string;
+/**
+ * 由应用连接串派生测试连接串：只改 schema，`host` / `port` / `database` 保持与应用一致。
+ *
+ * 派生是**幂等**的（`account` → `account_test`，`account_test` → `account_test`），
+ * 这样重复调用不会产生 `account_test_test`。
+ *
+ * 应用 schema 本身就以 `_test` 结尾时**直接拒绝**：此时派生结果与应用目标完全相同，测试会
+ * 清空应用数据。这是唯一需要「应用目标」才能发现的情况，所以把它固化成派生的一步——不需要
+ * 调用方额外传应用连接串、也不需要另开一道闸门。
+ */
+export declare function deriveTestDatabaseUrl(appDatabaseUrl: string): string;
+/** 环境闸门（实现在 `core/env.ts`，这里**只转出**：判定只有一份） */
+export { CLEANABLE_ENVS, assertCleanableEnvironment } from '../env.js';
+/** schema 闸门：目标 schema 必须以 `_test` 结尾（在**任何**同步 / 迁移 / 清理之前执行） */
+export declare function assertTestDatabaseSchema(testDatabaseUrl: string): void;
+/** `resolveTestDatabase()` 入参 */
+export interface TestDatabaseResolutionOptions {
+    /** 环境标记（`ENV`）；非可清理环境直接拒绝 */
+    env: string;
+    /** 显式测试连接串（`TEST_DATABASE_URL`）；优先级最高 */
+    testDatabaseUrl?: string;
+}
+/**
+ * 结算测试连接串，并**顺序**跑两道闸门：环境 → schema 命名。
+ *
+ * 顺序是刻意的：环境闸门决定「这台机器能不能做破坏性操作」，schema 闸门决定「目标名字是否
+ * 表示测试库」。
+ *
+ * 派生规则：显式 `testDatabaseUrl` 优先；否则由 `process.env.DATABASE_URL` 派生（schema
+ * 追加 `_test`，**幂等**）；两者都没有即拒绝——「猜一个连接串」在会清理数据的场景里不可接受。
+ */
+export declare function resolveTestDatabase(options: TestDatabaseResolutionOptions): string;
+export declare function parseConnectionString(connectionString: string): URL;
+//# sourceMappingURL=database.d.ts.map

package/output/core/test-support/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,UAAU,CAAA;AAQzC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAA;CACf;AAED,8CAA8C;AAC9C,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,cAAc,CAS9E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAShE;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAcpE;AAED,+CAA+C;AAC/C,OAAO,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAA;AACtE,kEAAkE;AAClE,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAUtE;AAED,iCAAiC;AACjC,MAAM,WAAW,6BAA6B;IAC5C,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,yCAAyC;IACzC,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,6BAA6B,GAAG,MAAM,CAiBlF;AAED,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,GAAG,CASnE"}

package/output/core/test-support/database.js

@@ -0,0 +1,131 @@
+/**
+ * 测试数据库安全检查（强制规则见 `@taicode/skills` 的 `test-database-isolation`）。
+ *
+ * 两道闸门，缺一不可：
+ *
+ * | 闸门 | 拒绝条件 | 缺失后的后果 |
+ * | --- | --- | --- |
+ * | 环境闸门 | `ENV` 不是可清理环境 | 生产 runner 上误跑破坏性测试 |
+ * | schema 闸门 | 目标 schema 不以 `_test` 结尾 | 绕过命名约定后仍能同步 / 清理应用 schema |
+ *
+ * 不需要「应用目标 vs 测试目标」比对：测试目标只由 `DATABASE_URL` **派生**得到（schema
+ * 追加 `_test`，幂等），再由 schema 闸门只放行 `*_test`。两条合起来，测试目标结构上不可能
+ * 是应用目标；再拿两个连接串互相比较，比的也只是同一份派生结果。
+ *
+ * ## 为什么在框架里
+ *
+ * 这套逻辑此前在 `account` / `expense` / `release` / `observai` 各写一遍，互相抄、互相漂移。
+ * 它保护的是**数据不丢**，属于「项目可以决定怎么实现，但不能决定要不要实现」的那类规则——
+ * 所以实现只能有一份，由框架提供；各仓的 `vitest.config.ts` / `global-setup.ts` 只调用，不复制。
+ *
+ * ## 为什么用 `throw` 而不是 `process.exit`
+ *
+ * 本模块被两类进程共用：
+ *
+ * - `createTestServer`（vitest worker 内）：退出码由 vitest 决定，抛错即该文件失败；
+ * - `vitest.config.ts` / `global-setup.ts`（配置与全局初始化）：抛错同样以非零状态结束进程。
+ *
+ * 抛错在两处都能得到「立刻失败」，而 `process.exit(1)` 在 worker 内会杀掉整个进程池、
+ * 丢掉其余文件的报告。错误信息本身必须足够定位，不能靠退出码表达。
+ */
+import { assertCleanableEnvironment } from '../env.js';
+/** 测试 schema 的强制后缀（`account` → `account_test`） */
+export const TEST_SCHEMA_SUFFIX = '_test';
+/** 连接串未写端口时按协议默认端口补齐后再比较（PostgreSQL 默认 5432） */
+const DEFAULT_POSTGRES_PORT = '5432';
+/** 连接串未写 `?schema=` 时的实际 schema（PostgreSQL 默认 `public`） */
+const DEFAULT_DATABASE_SCHEMA = 'public';
+/** 解析连接串的连接维度（解析失败即抛错：配置错误不该被当成「不同的目标」放过去） */
+export function resolveDatabaseTarget(connectionString) {
+    const parsed = parseConnectionString(connectionString);
+    return {
+        hostname: parsed.hostname,
+        port: parsed.port || DEFAULT_POSTGRES_PORT,
+        database: parsed.pathname.replace(/^\//, ''),
+        schema: parsed.searchParams.get('schema') ?? DEFAULT_DATABASE_SCHEMA,
+    };
+}
+/**
+ * 打印用的连接串（**密码一律替换为 `***`**）。
+ *
+ * 报错要能定位「连的是哪儿」，但不能把密码写进 CI 日志。
+ */
+export function maskDatabaseUrl(connectionString) {
+    const parsed = tryParseConnectionString(connectionString);
+    if (!parsed) {
+        return '<无法解析的连接串>';
+    }
+    if (parsed.password) {
+        parsed.password = '***';
+    }
+    return parsed.toString();
+}
+/**
+ * 由应用连接串派生测试连接串：只改 schema，`host` / `port` / `database` 保持与应用一致。
+ *
+ * 派生是**幂等**的（`account` → `account_test`，`account_test` → `account_test`），
+ * 这样重复调用不会产生 `account_test_test`。
+ *
+ * 应用 schema 本身就以 `_test` 结尾时**直接拒绝**：此时派生结果与应用目标完全相同，测试会
+ * 清空应用数据。这是唯一需要「应用目标」才能发现的情况，所以把它固化成派生的一步——不需要
+ * 调用方额外传应用连接串、也不需要另开一道闸门。
+ */
+export function deriveTestDatabaseUrl(appDatabaseUrl) {
+    const parsed = parseConnectionString(appDatabaseUrl);
+    const schema = parsed.searchParams.get('schema') ?? DEFAULT_DATABASE_SCHEMA;
+    if (schema.endsWith(TEST_SCHEMA_SUFFIX)) {
+        throw new Error(`[test-database] 应用连接串的 schema 已是 "${schema}"（以 ${TEST_SCHEMA_SUFFIX} 结尾），` +
+            `派生出的测试目标会与应用目标完全相同（${maskDatabaseUrl(appDatabaseUrl)}）。` +
+            '应用运行时 schema 绝不能以 _test 结尾：请修正 DATABASE_URL，而不是放宽守卫。');
+    }
+    parsed.searchParams.set('schema', `${schema}${TEST_SCHEMA_SUFFIX}`);
+    return parsed.toString();
+}
+/** 环境闸门（实现在 `core/env.ts`，这里**只转出**：判定只有一份） */
+export { CLEANABLE_ENVS, assertCleanableEnvironment } from '../env.js';
+/** schema 闸门：目标 schema 必须以 `_test` 结尾（在**任何**同步 / 迁移 / 清理之前执行） */
+export function assertTestDatabaseSchema(testDatabaseUrl) {
+    const { schema } = resolveDatabaseTarget(testDatabaseUrl);
+    if (schema.endsWith(TEST_SCHEMA_SUFFIX)) {
+        return;
+    }
+    throw new Error(`[test-database] 拒绝使用 schema "${schema}"：测试 schema 必须以 ${TEST_SCHEMA_SUFFIX} 结尾` +
+        `（当前目标 ${maskDatabaseUrl(testDatabaseUrl)}）。`);
+}
+/**
+ * 结算测试连接串，并**顺序**跑两道闸门：环境 → schema 命名。
+ *
+ * 顺序是刻意的：环境闸门决定「这台机器能不能做破坏性操作」，schema 闸门决定「目标名字是否
+ * 表示测试库」。
+ *
+ * 派生规则：显式 `testDatabaseUrl` 优先；否则由 `process.env.DATABASE_URL` 派生（schema
+ * 追加 `_test`，**幂等**）；两者都没有即拒绝——「猜一个连接串」在会清理数据的场景里不可接受。
+ */
+export function resolveTestDatabase(options) {
+    assertCleanableEnvironment(options.env);
+    const explicit = options.testDatabaseUrl || process.env.TEST_DATABASE_URL;
+    const base = process.env.DATABASE_URL;
+    const testDatabaseUrl = explicit || (base ? deriveTestDatabaseUrl(base) : '');
+    if (!testDatabaseUrl) {
+        throw new Error('[test-database] 无法确定测试连接串：TEST_DATABASE_URL 与 DATABASE_URL 都为空。' +
+            '会清理数据库的测试必须显式指向一个独立的 *_test schema。');
+    }
+    assertTestDatabaseSchema(testDatabaseUrl);
+    return testDatabaseUrl;
+}
+export function parseConnectionString(connectionString) {
+    const parsed = tryParseConnectionString(connectionString);
+    if (!parsed) {
+        throw new Error(`[test-database] 无法解析连接串 "${connectionString}"：测试连接目标必须可读，` +
+            '否则无法安全地派生 / 校验。检查 DATABASE_URL / TEST_DATABASE_URL 是否为合法 URL。');
+    }
+    return parsed;
+}
+function tryParseConnectionString(connectionString) {
+    try {
+        return new URL(connectionString);
+    }
+    catch {
+        return null;
+    }
+}

package/output/core/test-support/database.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=database.test.d.ts.map

package/output/core/test-support/database.test.d.ts.map

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

package/output/core/test-support/database.test.js

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { CLEANABLE_ENVS, assertCleanableEnvironment } from '../env.js';
+import { assertTestDatabaseSchema, deriveTestDatabaseUrl, maskDatabaseUrl, resolveDatabaseTarget, resolveTestDatabase, } from './database.js';
+/** 稳定的测试夹具（含密码，用于验证脱敏） */
+const APP_URL = 'postgresql://postgres:secret@db.internal:5432/taicode-labs?schema=account';
+/** 每个用例自行还原 env（`resolveTestDatabase` 会读 `process.env` 作为兜底） */
+const ORIGINAL_ENV = { ...process.env };
+afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+});
+describe('resolveDatabaseTarget', () => {
+    it('解析出四个连接维度（端口与 schema 按协议默认值补齐）', () => {
+        expect(resolveDatabaseTarget(APP_URL)).toEqual({
+            hostname: 'db.internal',
+            port: '5432',
+            database: 'taicode-labs',
+            schema: 'account',
+        });
+    });
+    it('未写端口时按 5432 补齐（否则 localhost 与 localhost:5432 会被误判为不同目标）', () => {
+        expect(resolveDatabaseTarget('postgresql://postgres@localhost/db').port).toBe('5432');
+    });
+    it('未写 schema 时按 public 补齐', () => {
+        expect(resolveDatabaseTarget('postgresql://postgres@localhost/db').schema).toBe('public');
+    });
+    it('连接串无法解析即抛错（不能把解析失败当成「不同的目标」放过去）', () => {
+        expect(() => resolveDatabaseTarget('not-a-url')).toThrow(/无法解析连接串/);
+    });
+});
+describe('deriveTestDatabaseUrl', () => {
+    it('只改 schema，host / port / database 保持与应用完全一致', () => {
+        const derived = resolveDatabaseTarget(deriveTestDatabaseUrl(APP_URL));
+        expect(derived).toEqual({
+            hostname: 'db.internal',
+            port: '5432',
+            database: 'taicode-labs',
+            schema: 'account_test',
+        });
+    });
+    it('应用 schema 已以 _test 结尾时拒绝：派生结果会与应用目标完全相同', () => {
+        // 这是唯一需要「应用目标」才能发现的情况，因此固化成派生的一步。
+        expect(() => deriveTestDatabaseUrl('postgresql://postgres:secret@db.internal:5432/taicode-labs?schema=account_test')).toThrow(/派生出的测试目标会与应用目标完全相同/);
+    });
+    it('保留密码与查询参数里的其它键', () => {
+        const derived = new URL(deriveTestDatabaseUrl(`${APP_URL}&sslmode=require`));
+        expect(derived.password).toBe('secret');
+        expect(derived.searchParams.get('sslmode')).toBe('require');
+    });
+});
+describe('maskDatabaseUrl', () => {
+    it('隐藏密码（报错要能定位目标，但不能把密码写进 CI 日志）', () => {
+        const masked = maskDatabaseUrl(APP_URL);
+        expect(masked).not.toContain('secret');
+        expect(masked).toContain('***');
+        expect(masked).toContain('db.internal');
+    });
+    it('无法解析时给出占位而不是抛错（它只用于报错信息）', () => {
+        expect(maskDatabaseUrl('not-a-url')).toBe('<无法解析的连接串>');
+    });
+});
+describe('assertCleanableEnvironment（环境闸门）', () => {
+    it.each(CLEANABLE_ENVS)('放行可清理环境 %s', (env) => {
+        expect(() => assertCleanableEnvironment(env)).not.toThrow();
+    });
+    it('拒绝生产环境，并在错误里写明当前值与可接受值', () => {
+        expect(() => assertCleanableEnvironment('production')).toThrow(/ENV="production"/);
+    });
+    it('拒绝未设置的空值（默认放行等于把守卫关掉）', () => {
+        expect(() => assertCleanableEnvironment('')).toThrow(/<未设置>/);
+    });
+});
+describe('assertTestDatabaseSchema（schema 闸门）', () => {
+    it('放行 *_test', () => {
+        expect(() => assertTestDatabaseSchema('postgresql://postgres@localhost/db?schema=account_test')).not.toThrow();
+    });
+    it('拒绝非 *_test（在同步 / 迁移 / 清理之前就失败）', () => {
+        expect(() => assertTestDatabaseSchema(APP_URL)).toThrow(/account/);
+    });
+});
+describe('resolveTestDatabase（两道闸门串联 + 派生）', () => {
+    it('无任何变量时拒绝（猜测连接串在会清理数据的场景里不可接受）', () => {
+        delete process.env.DATABASE_URL;
+        delete process.env.TEST_DATABASE_URL;
+        expect(() => resolveTestDatabase({ env: 'development' })).toThrow(/无法确定测试连接串/);
+    });
+    it('显式 TEST_DATABASE_URL 优先于派生', () => {
+        process.env.DATABASE_URL = APP_URL;
+        process.env.TEST_DATABASE_URL = 'postgresql://postgres:secret@db.internal:5432/taicode-labs?schema=explicit_test';
+        expect(resolveTestDatabase({ env: 'development' })).toContain('explicit_test');
+    });
+    it('没有显式变量时由 DATABASE_URL 派生', () => {
+        process.env.DATABASE_URL = APP_URL;
+        delete process.env.TEST_DATABASE_URL;
+        expect(resolveDatabaseTarget(resolveTestDatabase({ env: 'development' })).schema).toBe('account_test');
+    });
+    it('顺序：环境闸门先于 schema 闸门（生产环境下不先抱怨 schema 名）', () => {
+        process.env.TEST_DATABASE_URL = APP_URL;
+        expect(() => resolveTestDatabase({ env: 'production' })).toThrow(/拒绝在 ENV="production"/);
+    });
+    it('通过闸门后返回可用的测试连接串', () => {
+        process.env.DATABASE_URL = APP_URL;
+        delete process.env.TEST_DATABASE_URL;
+        const resolved = resolveTestDatabase({ env: 'development' });
+        expect(resolveDatabaseTarget(resolved)).toEqual({
+            hostname: 'db.internal',
+            port: '5432',
+            database: 'taicode-labs',
+            schema: 'account_test',
+        });
+    });
+});

package/output/core/test-support/environment.d.ts

@@ -0,0 +1,38 @@
+import type { ConfigEnv } from '../env.js';
+/**
+ * **工具进程**的环境出口。
+ *
+ * `startServer` / `createTestServer` 覆盖不到的进程（`prisma.config.ts`、`scripts/*.ts`、以及被
+ * 它们静态 import 的配置模块）只能自己开口要 env：ES 模块顶层求值早于入口函数执行，所以
+ * 「入口里加载 env」救不了这些文件。
+ *
+ * 只加载、不做任何闸门——运行期配置不该带上测试闸门，那会给正常启动平白加一道无关检查。
+ * 幂等：重复调用只是重复读 `dotenv`。
+ */
+export declare function loadRuntimeEnvironment(): ConfigEnv;
+/**
+ * 结算**测试**数据库目标：加载测试层 → 闸门 → 结算 → 把测试连接串注入返回的 env 快照。
+ *
+ * **`createTestServer` 的私有步骤，不对外导出。** 导出它等于让调用方自己决定「什么时候跑
+ * 闸门、按什么顺序」，而顺序本身就是安全前提。
+ *
+ * 顺序（固定，不开放重排）：
+ * ```
+ * 加载 .env.dev < .env < .env.local < .env.test < .env.test.local（ENV 未给时兜底 test）
+ *   → 环境闸门（ENV 必须可清理）
+ *   → 结算（显式 TEST_DATABASE_URL 优先，否则由 DATABASE_URL 派生 +_test，幂等）
+ *   → schema 闸门（必须以 _test 结尾）
+ *   → 把测试连接串写进**返回的 env 快照**（不碰全局 process.env）
+ * ```
+ *
+ * **为什么不再改写 `process.env.DATABASE_URL`**：那是进程级副作用——同一进程里并行跑多个
+ * `createTestServer`（或测试与被测代码共享进程）时会互相覆写，谁最后写谁赢。测试目标应当
+ * 只属于**本次装配**：框架把它注入到返回的 `env` 快照里，`resources` 槽位从 `ctx.env.DATABASE_URL`
+ * 读取（框架契约：资源只读 `ctx.env`，不读 `process.env`），因此每个实例各连各的，互不干扰。
+ *
+ * 隔离比较不在这里：返回的 `env.DATABASE_URL` 此时就是测试目标，比对恒等于「自比自」。
+ * 防止测试清空应用数据靠的是**派生 + `_test` schema 闸门**——派生只会追加后缀，schema 闸门
+ * 只放行 `*_test`，所以测试目标结构上不可能是应用目标。
+ */
+export declare function prepareTestDatabase(): ConfigEnv;
+//# sourceMappingURL=environment.d.ts.map

package/output/core/test-support/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/environment.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,IAAI,SAAS,CAElD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,CAO/C"}

package/output/core/test-support/environment.js

@@ -0,0 +1,45 @@
+import { loadEnvironment, resolveConfigEnv } from '../env.js';
+import { resolveTestDatabase } from './database.js';
+/**
+ * **工具进程**的环境出口。
+ *
+ * `startServer` / `createTestServer` 覆盖不到的进程（`prisma.config.ts`、`scripts/*.ts`、以及被
+ * 它们静态 import 的配置模块）只能自己开口要 env：ES 模块顶层求值早于入口函数执行，所以
+ * 「入口里加载 env」救不了这些文件。
+ *
+ * 只加载、不做任何闸门——运行期配置不该带上测试闸门，那会给正常启动平白加一道无关检查。
+ * 幂等：重复调用只是重复读 `dotenv`。
+ */
+export function loadRuntimeEnvironment() {
+    return loadEnvironment();
+}
+/**
+ * 结算**测试**数据库目标：加载测试层 → 闸门 → 结算 → 把测试连接串注入返回的 env 快照。
+ *
+ * **`createTestServer` 的私有步骤，不对外导出。** 导出它等于让调用方自己决定「什么时候跑
+ * 闸门、按什么顺序」，而顺序本身就是安全前提。
+ *
+ * 顺序（固定，不开放重排）：
+ * ```
+ * 加载 .env.dev < .env < .env.local < .env.test < .env.test.local（ENV 未给时兜底 test）
+ *   → 环境闸门（ENV 必须可清理）
+ *   → 结算（显式 TEST_DATABASE_URL 优先，否则由 DATABASE_URL 派生 +_test，幂等）
+ *   → schema 闸门（必须以 _test 结尾）
+ *   → 把测试连接串写进**返回的 env 快照**（不碰全局 process.env）
+ * ```
+ *
+ * **为什么不再改写 `process.env.DATABASE_URL`**：那是进程级副作用——同一进程里并行跑多个
+ * `createTestServer`（或测试与被测代码共享进程）时会互相覆写，谁最后写谁赢。测试目标应当
+ * 只属于**本次装配**：框架把它注入到返回的 `env` 快照里，`resources` 槽位从 `ctx.env.DATABASE_URL`
+ * 读取（框架契约：资源只读 `ctx.env`，不读 `process.env`），因此每个实例各连各的，互不干扰。
+ *
+ * 隔离比较不在这里：返回的 `env.DATABASE_URL` 此时就是测试目标，比对恒等于「自比自」。
+ * 防止测试清空应用数据靠的是**派生 + `_test` schema 闸门**——派生只会追加后缀，schema 闸门
+ * 只放行 `*_test`，所以测试目标结构上不可能是应用目标。
+ */
+export function prepareTestDatabase() {
+    const loaded = loadEnvironment({ mode: 'test' });
+    const databaseUrl = resolveTestDatabase({ env: loaded.ENV });
+    // 只注入到本次装配的 env 快照，**不改写全局 process.env.DATABASE_URL**（避免进程级串扰）
+    return { ...resolveConfigEnv(), DATABASE_URL: databaseUrl };
+}

package/output/core/test-support/service-context.d.ts

@@ -0,0 +1,64 @@
+import type { ClientsView, LoggerLike, ResourcesView, ServiceContext } from '../types.js';
+/**
+ * `createTestServiceContext()` —— **单元级**测试构造 `services` 槽位入参的唯一方式。
+ *
+ * ## 为什么框架要给这个出口
+ *
+ * `createTestServer()` 是**集成**测试的唯一入口：它跑全量装配（resources → config →
+ * clients → services → routers），代价是「每条用例都要连真库、装全部路由」。只想验一个
+ * service 函数的判断逻辑时，这个代价与收益不成比例——于是各仓各自写了一份
+ * `createServiceContext(fakeDb, { ... })`，还都带着同一句
+ * `as unknown as AccountServiceContext`：**同一个绕过动作被抄了四遍**，说明缺的是
+ * 框架能力，不是各仓的疏忽。
+ *
+ * 这里的取舍是明确的：**不伪造能力，只允许缺省能力**。
+ * - 传进来的 `resources` / `clients` 是**真实对象**（真 reader、真 db 客户端、注入式
+ *   替身），不是 mock 框架的代理——本函数不生成任何行为，只做装配。
+ * - 没传的能力被访问时**抛错**（错误信息点名是哪个键），而不是返回 `undefined` 让调用方
+ *   的 `undefined.xxx` 在更远处炸开。这区分了「这个单元不该碰数据库」与「忘了给数据库」
+ *   两种完全不同的失败。
+ *
+ * ## 为什么不干脆把 `ctx` 收窄成「这个服务用到的字段」
+ *
+ * 那会让「服务工厂第一参数恒为 ctx」这条约定退化：每个工厂的入参类型各不相同，装配层
+ * 就无法把一份 ctx 原样传下去（`createServices` 得为每个服务裁一次类型）。约定要留，
+ * 代价就由本函数承担——它给出**形状完整、能力可缺省**的 ctx。
+ *
+ * ## `resources.<key>` 为什么用 Proxy 而不是浅合并空对象
+ *
+ * 浅合并只能发现问题的一半：`resources.database` 变成了 `undefined`，错误发生在
+ * `undefined.user.findMany()` 上，栈里全都是业务代码，看不出根因是「这份 ctx 没给
+ * database」。Proxy 让错误在**取字段的那一行**抛出并点名，测试写错时的定位成本从
+ * 「翻业务代码」降到「看一行错误」。
+ */
+export interface TestServiceContextOptions<Resources, Config, Clients> {
+    /**
+     * 提供被测单元**实际读到**的资源能力（其余键访问即抛错）。
+     *
+     * 传真实实例：真 `PrismaClient`、`createSystemConfigReader(db)`，或对**外部 I/O
+     * 边界**（第三方 HTTP、邮件网关）注入的替身。不要替身框架自己的装配。
+     */
+    resources?: Partial<ResourcesView<Resources>>;
+    /** 提供被测单元**实际读到**的客户端（其余键访问即抛错） */
+    clients?: Partial<ClientsView<Clients>>;
+    /** `config` 产物；被测单元按契约不读它时省略（读取会抛错，不会拿到 `undefined`） */
+    config?: Awaited<Config>;
+    /** 日志出口覆盖（缺省为静默 no-op；断言日志时传 `vi.fn()` 组成的实现） */
+    log?: Partial<LoggerLike>;
+}
+/**
+ * 构造 `services` 槽位的测试入参（`ServiceContext`）。
+ *
+ * ```ts
+ * const ctx = createTestServiceContext<AccountResources, AccountConfig>({
+ *   resources: { systemConfig: fakeReader },
+ *   log: { warn: warnSpy },
+ * })
+ * const service = createRuntimeConfigService(ctx)
+ * ```
+ *
+ * 返回的 `disposer` 是**真实** `Disposer`：被测单元登记的释放函数会真的被收集，
+ * 测试可以用 `await ctx.disposer.dispose()` 验证「服务自己登记了释放」这条契约。
+ */
+export declare function createTestServiceContext<Resources, Config, Clients = unknown>(options?: TestServiceContextOptions<Resources, Config, Clients>): ServiceContext<Resources, Config, Clients>;
+//# sourceMappingURL=service-context.d.ts.map

package/output/core/test-support/service-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-context.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/service-context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAEzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO;IACnE;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAA;IAC7C,mCAAmC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAA;IACvC,wDAAwD;IACxD,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IACxB,iDAAiD;IACjD,GAAG,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAA;CAC1B;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,EAC3E,OAAO,GAAE,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAM,GAClE,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAoB5C"}

package/output/core/test-support/service-context.js

@@ -0,0 +1,63 @@
+import { Disposer } from '@taicode/common-base';
+/** 缺省日志：静默。测试不该因为「服务打了一行 info」而需要准备 logger。 */
+const SILENT_LOG = {
+    debug: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+/**
+ * 构造 `services` 槽位的测试入参（`ServiceContext`）。
+ *
+ * ```ts
+ * const ctx = createTestServiceContext<AccountResources, AccountConfig>({
+ *   resources: { systemConfig: fakeReader },
+ *   log: { warn: warnSpy },
+ * })
+ * const service = createRuntimeConfigService(ctx)
+ * ```
+ *
+ * 返回的 `disposer` 是**真实** `Disposer`：被测单元登记的释放函数会真的被收集，
+ * 测试可以用 `await ctx.disposer.dispose()` 验证「服务自己登记了释放」这条契约。
+ */
+export function createTestServiceContext(options = {}) {
+    // 释放器是真实的：登记 / 逆序执行都是被测契约的一部分，不能替身掉
+    const disposer = new Disposer({ label: 'test-service-context', log: SILENT_LOG });
+    return {
+        log: { ...SILENT_LOG, ...options.log },
+        disposer,
+        resources: requireProvided(options.resources, 'resources'),
+        clients: requireProvided(options.clients, 'clients'),
+        get config() {
+            if (options.config === undefined) {
+                throw new Error('[test-service-context] 这份 ctx 没有提供 config：' +
+                    '被测单元按契约不读 config（运行期配置一律经 resources.systemConfig）。' +
+                    '若确实要读，请通过 createTestServiceContext({ config }) 显式给出。');
+            }
+            return options.config;
+        },
+    };
+}
+/**
+ * 把「部分提供」包装成「形状完整、缺省即抛错」的视图。
+ *
+ * 只在**读取被缺省的键**时抛错：传了的键行为与真实视图完全一致（同一个对象、同一份
+ * 引用），所以注入式替身与真实例都照常工作。
+ */
+function requireProvided(provided, label) {
+    const source = provided ?? {};
+    return new Proxy(source, {
+        get(target, key, receiver) {
+            // Symbol（`Symbol.toStringTag`、`then` 探测等）与 `in` 都按普通对象处理
+            if (typeof key === 'symbol') {
+                return Reflect.get(target, key, receiver);
+            }
+            if (!(key in target)) {
+                throw new Error(`[test-service-context] 这份 ctx 没有提供 ${label}.${key}：` +
+                    `被测单元读到了它，说明它确实依赖这项能力——请通过 createTestServiceContext({ ${label}: { ${key}: … } }) 给出` +
+                    '（真实实例或对外部 I/O 边界的替身，不要替身框架自身的装配）。');
+            }
+            return Reflect.get(target, key, receiver);
+        },
+    });
+}

package/output/core/test-support/service-context.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=service-context.test.d.ts.map

package/output/core/test-support/service-context.test.d.ts.map

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

package/output/core/test-support/service-context.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createTestServiceContext } from './service-context.js';
+describe('createTestServiceContext', () => {
+    it('提供的资源与客户端原样可用（同一个引用，不做拷贝）', () => {
+        const database = { user: { count: async () => 3 } };
+        const cache = { get: () => undefined };
+        const ctx = createTestServiceContext({
+            resources: { database },
+            clients: { cache },
+        });
+        expect(ctx.resources.database).toBe(database);
+        expect(ctx.clients.cache).toBe(cache);
+    });
+    it('读取被缺省的能力时当场抛错，错误点名是哪个键', () => {
+        const ctx = createTestServiceContext({
+            resources: { database: { user: { count: async () => 0 } } },
+        });
+        // 提供的键正常
+        expect(ctx.resources.database).toBeDefined();
+        // 未提供的键：取字段那一步就抛，而不是返回 undefined 留到业务代码里炸
+        expect(() => ctx.resources.systemConfig).toThrowError(/resources\.systemConfig/);
+    });
+    it('缺省能力抛错信息里给出补法（createTestServiceContext({ resources: { … } })）', () => {
+        const ctx = createTestServiceContext();
+        expect(() => ctx.clients.anything).toThrowError(/createTestServiceContext\(\{ clients: \{ anything: … \} \}\)/);
+    });
+    it('未给 config 时读取抛错（不会拿到 undefined）', () => {
+        const ctx = createTestServiceContext();
+        expect(() => ctx.config).toThrowError(/没有提供 config/);
+    });
+    it('给了 config 时按传入值返回', () => {
+        const ctx = createTestServiceContext({
+            config: { featureEnabled: true },
+        });
+        expect(ctx.config).toEqual({ featureEnabled: true });
+    });
+    it('disposer 是真实的：登记的清理会被收集并按逆序执行', async () => {
+        const ctx = createTestServiceContext();
+        const order = [];
+        // 模拟「服务在构造期自己登记释放」这条契约
+        ctx.disposer.add(() => order.push('first'));
+        ctx.disposer.add(() => order.push('second'));
+        await ctx.disposer.dispose();
+        expect(order).toEqual(['second', 'first']);
+    });
+    it('日志缺省静默；覆盖后能断言调用', () => {
+        const warn = vi.fn();
+        const silent = createTestServiceContext();
+        const spying = createTestServiceContext({ log: { warn } });
+        // 缺省实现不抛错（pino 之外不要强制测试准备 logger）
+        expect(() => silent.log.warn({ a: 1 }, 'hello')).not.toThrow();
+        spying.log.warn({ a: 1 }, 'hello');
+        expect(warn).toHaveBeenCalledWith({ a: 1 }, 'hello');
+    });
+});