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

package/output/app/env.d.ts

@@ -1,59 +0,0 @@
-/**
- * 默认 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 ①：与现状逐字一致）。
- */
-export declare const ENV_FILE_LAYERS: readonly [".env.dev", ".env", ".env.local"];
-/** `ENV=test` 时追加的最高层（设计 §3.1 ①） */
-export declare const TEST_ENV_FILE_LAYER = ".env.test.local";
-/** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
-export declare const DEFAULT_LOG_LEVEL = "info";
-/**
- * 按分层顺序加载 env 文件（设计 §3.1 ①）。
- *
- * `startServer` 内部会**固定调用**本函数；工具进程（`vitest.config.ts` / `scripts/*.ts`）不在
- * `startServer` 覆盖范围内，须自行显式调用本函数。
- *
- * @param extraLayers 追加在最高优先级的额外层，例如测试配置传 `['.env.test.local']`
- */
-export declare function loadEnvFiles(extraLayers?: readonly string[]): void;
-/**
- * 框架在配置前固定加载的 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（不加载文件）；`startServer` 会先 `loadRuntimeEnvFiles()` 再调用本函数 */
-export declare function resolveConfigEnv(): ConfigEnv;
-/**
- * `startServer` 最早阶段的固定 env 加载（设计 §3.1 ①）：
- * `.env.dev < .env < .env.local`（外部注入最高），`ENV=test` 时再追加 `.env.test.local`。
- *
- * 注意 `generateOpenApi` **不**调用本函数（它不要求配置有效，设计 §3.2 规则 A/B）。
- */
-export declare function loadRuntimeEnvFiles(): ConfigEnv;
-//# sourceMappingURL=env.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../source/app/env.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,6CAA8C,CAAA;AAE1E,oCAAoC;AACpC,eAAO,MAAM,mBAAmB,oBAAoB,CAAA;AAEpD,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,SAAS,CAAA;AAUvC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,WAAW,GAAE,SAAS,MAAM,EAAO,GAAG,IAAI,CAUtE;AAED;;;;;;;;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,sEAAsE;AACtE,wBAAgB,gBAAgB,IAAI,SAAS,CAQ5C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,CAM/C"}

package/output/app/env.js

@@ -1,66 +0,0 @@
-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 ①：与现状逐字一致）。
- */
-export const ENV_FILE_LAYERS = ['.env.dev', '.env', '.env.local'];
-/** `ENV=test` 时追加的最高层（设计 §3.1 ①） */
-export const TEST_ENV_FILE_LAYER = '.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 文件（设计 §3.1 ①）。
- *
- * `startServer` 内部会**固定调用**本函数；工具进程（`vitest.config.ts` / `scripts/*.ts`）不在
- * `startServer` 覆盖范围内，须自行显式调用本函数。
- *
- * @param extraLayers 追加在最高优先级的额外层，例如测试配置传 `['.env.test.local']`
- */
-export function loadEnvFiles(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（不加载文件）；`startServer` 会先 `loadRuntimeEnvFiles()` 再调用本函数 */
-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,
-    };
-}
-/**
- * `startServer` 最早阶段的固定 env 加载（设计 §3.1 ①）：
- * `.env.dev < .env < .env.local`（外部注入最高），`ENV=test` 时再追加 `.env.test.local`。
- *
- * 注意 `generateOpenApi` **不**调用本函数（它不要求配置有效，设计 §3.2 规则 A/B）。
- */
-export function loadRuntimeEnvFiles() {
-    loadEnvFiles();
-    if ((process.env.ENV ?? '') === 'test') {
-        loadEnvFiles([TEST_ENV_FILE_LAYER]);
-    }
-    return resolveConfigEnv();
-}

package/output/app/env.test.js

@@ -1,124 +0,0 @@
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-/**
- * env 加载契约（设计 §3.1 ①）。
- *
- * 固定约定：`.env.dev` < `.env` < `.env.local`（外部注入最高），`ENV=test` 追加 `.env.test.local`；
- * 固定读取 `ENV` / `API_PORT` / `LOG_LEVEL`，端口**只读 `API_PORT`，绝不回退 `PORT`**。
- */
-const ENV_KEYS = [
-    'LAYER',
-    'OVERRIDE',
-    'ONLY_DEV',
-    'ONLY_ENV',
-    'ONLY_LOCAL',
-    'EXTERNAL_ONLY',
-    'ONLY_TEST',
-    'EXPORTED',
-    'QUOTED',
-    'MULTI',
-    'HASHED',
-    'ENV',
-    'API_PORT',
-    'PORT',
-    'LOG_LEVEL',
-];
-function clearEnvKeys() {
-    for (const key of ENV_KEYS) {
-        delete process.env[key];
-    }
-}
-/** 重新求值 `env.js`（`EXTERNAL_ENV` 快照在模块首次求值时抓取） */
-async function importEnvModule() {
-    vi.resetModules();
-    return import('./env.js');
-}
-describe('env 加载（设计 §3.1 ①）', () => {
-    let previousCwd;
-    let directory;
-    beforeEach(() => {
-        previousCwd = process.cwd();
-        directory = mkdtempSync(join(tmpdir(), 'common-app-env-'));
-        writeFileSync(join(directory, '.env.dev'), 'LAYER=dev\nONLY_DEV=dev\nOVERRIDE=dev\n');
-        writeFileSync(join(directory, '.env'), 'LAYER=env\nONLY_ENV=env\nOVERRIDE=env\n');
-        writeFileSync(join(directory, '.env.local'), 'LAYER=local\nONLY_LOCAL=local\nOVERRIDE=local\n');
-        process.chdir(directory);
-        clearEnvKeys();
-    });
-    afterEach(() => {
-        process.chdir(previousCwd);
-        rmSync(directory, { recursive: true, force: true });
-        clearEnvKeys();
-        vi.resetModules();
-    });
-    it('分层优先级：外部注入 > .env.local > .env > .env.dev', async () => {
-        process.env.LAYER = 'external';
-        process.env.EXTERNAL_ONLY = 'external';
-        const { loadEnvFiles } = await importEnvModule();
-        loadEnvFiles();
-        expect(process.env.LAYER).toBe('external');
-        expect(process.env.EXTERNAL_ONLY).toBe('external');
-        expect(process.env.OVERRIDE).toBe('local');
-        expect(process.env.ONLY_DEV).toBe('dev');
-        expect(process.env.ONLY_ENV).toBe('env');
-        expect(process.env.ONLY_LOCAL).toBe('local');
-    });
-    it('追加层（如 .env.test.local）优先级最高', async () => {
-        writeFileSync(join(directory, '.env.test.local'), 'OVERRIDE=test-local\nONLY_TEST=1\n');
-        const { loadEnvFiles } = await importEnvModule();
-        loadEnvFiles(['.env.test.local']);
-        expect(process.env.OVERRIDE).toBe('test-local');
-        expect(process.env.ONLY_TEST).toBe('1');
-    });
-    it('缺失的 env 文件不报错，已有层照常生效', async () => {
-        rmSync(join(directory, '.env.local'));
-        const { loadEnvFiles } = await importEnvModule();
-        expect(() => loadEnvFiles()).not.toThrow();
-        expect(process.env.ONLY_DEV).toBe('dev');
-        expect(process.env.OVERRIDE).toBe('env');
-    });
-    it('dotenv 语义：export 前缀 / 引号 / 转义 / 多行 / 行尾注释（与四家现状逐字一致）', async () => {
-        writeFileSync(join(directory, '.env.local'), ['export EXPORTED=1', 'QUOTED="a b"', 'MULTI="line1\\nline2"', 'HASHED=value # 行尾注释'].join('\n'));
-        const { loadEnvFiles } = await importEnvModule();
-        loadEnvFiles();
-        expect(process.env.EXPORTED).toBe('1');
-        expect(process.env.QUOTED).toBe('a b');
-        expect(process.env.MULTI).toBe('line1\nline2');
-        expect(process.env.HASHED).toBe('value');
-    });
-    it('loadRuntimeEnvFiles：ENV=test 时追加 .env.test.local', async () => {
-        writeFileSync(join(directory, '.env.dev'), 'LAYER=dev\nOVERRIDE=dev\nENV=test\nAPI_PORT=4321\n');
-        writeFileSync(join(directory, '.env.test.local'), 'LOG_LEVEL=debug\nONLY_TEST=1\n');
-        const { loadRuntimeEnvFiles } = await importEnvModule();
-        const env = loadRuntimeEnvFiles();
-        expect(env.ENV).toBe('test');
-        expect(env.API_PORT).toBe('4321');
-        expect(env.LOG_LEVEL).toBe('debug');
-        expect(process.env.ONLY_TEST).toBe('1');
-    });
-    it('loadRuntimeEnvFiles：ENV 非 test 时不加载 .env.test.local', async () => {
-        writeFileSync(join(directory, '.env.local'), 'ENV=development\n');
-        writeFileSync(join(directory, '.env.test.local'), 'LOG_LEVEL=debug\nONLY_TEST=1\n');
-        const { loadRuntimeEnvFiles } = await importEnvModule();
-        const env = loadRuntimeEnvFiles();
-        expect(env.ENV).toBe('development');
-        expect(env.LOG_LEVEL).toBe('info');
-        expect(process.env.ONLY_TEST).toBeUndefined();
-    });
-    it('固定读取：只认 API_PORT（绝不回退 PORT），LOG_LEVEL 默认 info，ENV 缺省空串', async () => {
-        process.env.PORT = '9999';
-        const { resolveConfigEnv } = await importEnvModule();
-        const env = resolveConfigEnv();
-        expect(env.API_PORT).toBe('');
-        expect(env.LOG_LEVEL).toBe('info');
-        expect(env.ENV).toBe('');
-    });
-    it('固有常量：分层顺序 / 测试层 / 默认日志级别', async () => {
-        const { ENV_FILE_LAYERS, TEST_ENV_FILE_LAYER, DEFAULT_LOG_LEVEL } = await importEnvModule();
-        expect(ENV_FILE_LAYERS).toEqual(['.env.dev', '.env', '.env.local']);
-        expect(TEST_ENV_FILE_LAYER).toBe('.env.test.local');
-        expect(DEFAULT_LOG_LEVEL).toBe('info');
-    });
-});

package/output/app/error-contract.test.d.ts

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

package/output/app/error-contract.test.d.ts.map

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

package/output/app/error-contract.test.js

@@ -1,125 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { z } from 'zod';
-import { defineServer, startServer } from './entries.js';
-import { SystemError, UserError } from './errors.js';
-/**
- * 错误契约——**强制、不可配置**。
- *
- * 响应信封 `{ status, message, data }`（错误时 `data: null`，`status` 放错误码字符串）；
- * 映射固定：`UserError`→400（`error.status` 字面量）/ `SystemError`→500 / zod→400 / 未知→500 /
- * 未匹配路由→404。错误只给稳定**码**，文案不归框架。
- */
-/** zod validator 由 core 的 `schema` 统一装配，运行时按 zod 校验（类型上仍是 FastifySchema） */
-const validatedQuerySchema = {
-    querystring: z.object({ count: z.coerce.number().int().min(1) }),
-};
-function createErrorContractServer() {
-    return defineServer({
-        app: { service: 'error-contract', title: 'Error Contract', version: '1.0.0' },
-        resources: () => ({}),
-        config: () => ({}),
-        services: () => ({}),
-        middlewares: () => [],
-        routers: (ctx) => {
-            ctx.app.get('/ok', () => ({ hello: 'world' }));
-            ctx.app.get('/envelope', () => ({ status: 'CUSTOM', message: 'm', data: 1 }));
-            ctx.app.get('/user-error', () => {
-                throw new UserError('INVALID_TOKEN', undefined, 'token 无效');
-            });
-            ctx.app.get('/system-error', () => {
-                throw new SystemError('DATABASE_UNAVAILABLE', undefined, '数据库不可用');
-            });
-            ctx.app.get('/unknown-error', () => {
-                throw new Error('boom');
-            });
-            ctx.app.get('/validated', { schema: validatedQuerySchema }, (request) => ({
-                count: request.query.count,
-            }));
-        },
-    });
-}
-describe('错误契约', () => {
-    it('成功信封：{ status: SUCCESS, message: ok, data }', async () => {
-        const app = await startServer(createErrorContractServer(), { listen: false });
-        const response = await app.inject({ method: 'GET', url: '/ok' });
-        expect(response.statusCode).toBe(200);
-        expect(response.json()).toEqual({ status: 'SUCCESS', message: 'ok', data: { hello: 'world' } });
-        await app.close();
-    });
-    it('已是信封的载荷不被二次包裹', async () => {
-        const app = await startServer(createErrorContractServer(), { listen: false });
-        const response = await app.inject({ method: 'GET', url: '/envelope' });
-        expect(response.statusCode).toBe(200);
-        expect(response.json()).toEqual({ status: 'CUSTOM', message: 'm', data: 1 });
-        await app.close();
-    });
-    it('UserError → 400（取 `error.status` 字面量），status 放错误码、data 为 null', async () => {
-        const app = await startServer(createErrorContractServer(), { listen: false });
-        const response = await app.inject({ method: 'GET', url: '/user-error' });
-        expect(response.statusCode).toBe(400);
-        expect(response.json()).toEqual({ status: 'INVALID_TOKEN', message: 'token 无效', data: null });
-        await app.close();
-    });
-    it('SystemError → 500（取 `error.status` 字面量）', async () => {
-        const app = await startServer(createErrorContractServer(), { listen: false });
-        const response = await app.inject({ method: 'GET', url: '/system-error' });
-        expect(response.statusCode).toBe(500);
-        expect(response.json()).toEqual({ status: 'DATABASE_UNAVAILABLE', message: '数据库不可用', data: null });
-        await app.close();
-    });
-    it('未知错误 → 500 + UNKNOWN_ERROR', async () => {
-        const app = await startServer(createErrorContractServer(), { listen: false });
-        const response = await app.inject({ method: 'GET', url: '/unknown-error' });
-        expect(response.statusCode).toBe(500);
-        expect(response.json()).toEqual({ status: 'UNKNOWN_ERROR', message: 'boom', data: null });
-        await app.close();
-    });
-    it('zod 校验失败 → 400（INVALID_INPUT）；通过校验 → 200', async () => {
-        const app = await startServer(createErrorContractServer(), { listen: false });
-        const invalid = await app.inject({ method: 'GET', url: '/validated?count=0' });
-        expect(invalid.statusCode).toBe(400);
-        const invalidBody = invalid.json();
-        expect(invalidBody.status).toBe('INVALID_INPUT');
-        expect(invalidBody.data).toBeNull();
-        expect(invalidBody.message).toContain('count');
-        const valid = await app.inject({ method: 'GET', url: '/validated?count=3' });
-        expect(valid.statusCode).toBe(200);
-        expect(valid.json()).toEqual({ status: 'SUCCESS', message: 'ok', data: { count: 3 } });
-        await app.close();
-    });
-    it('未匹配路由 → 404 + NOT_IMPLEMENTED', async () => {
-        const app = await startServer(createErrorContractServer(), { listen: false });
-        const response = await app.inject({ method: 'GET', url: '/missing' });
-        expect(response.statusCode).toBe(404);
-        const body = response.json();
-        expect(body.status).toBe('NOT_IMPLEMENTED');
-        expect(body.data).toBeNull();
-        expect(body.message).toContain('GET /missing');
-        await app.close();
-    });
-    it('资源包里的 `classifyError` 被用作数据层错误分类（→500）', async () => {
-        const server = defineServer({
-            app: { service: 'error-contract-database', title: 'Error Contract Database', version: '1.0.0' },
-            resources: () => ({
-                database: {
-                    classifyError: (error) => error instanceof Error && error.message === 'pg down'
-                        ? new SystemError('DATABASE_ERROR', { operation: 'query' }, 'pg down')
-                        : null,
-                },
-            }),
-            config: () => ({}),
-            services: () => ({}),
-            middlewares: () => [],
-            routers: (ctx) => {
-                ctx.app.get('/database-down', () => {
-                    throw new Error('pg down');
-                });
-            },
-        });
-        const app = await startServer(server, { listen: false });
-        const response = await app.inject({ method: 'GET', url: '/database-down' });
-        expect(response.statusCode).toBe(500);
-        expect(response.json()).toEqual({ status: 'DATABASE_ERROR', message: 'pg down', data: null });
-        await app.close();
-    });
-});

package/output/app/errors.d.ts

@@ -1,20 +0,0 @@
-import type { ErrorContext } from '@taicode/common-base';
-export declare class UserError extends Error {
-    readonly type: string;
-    readonly context?: ErrorContext | undefined;
-    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
-    static is(value: unknown): value is UserError;
-    /** 固定 HTTP 状态（字面量类型） */
-    readonly status: 400;
-    constructor(type: string, context?: ErrorContext | undefined, message?: string);
-}
-export declare class SystemError extends Error {
-    readonly type: string;
-    readonly context?: ErrorContext | undefined;
-    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
-    static is(value: unknown): value is SystemError;
-    /** 固定 HTTP 状态（字面量类型） */
-    readonly status: 500;
-    constructor(type: string, context?: ErrorContext | undefined, message?: string);
-}
-//# sourceMappingURL=errors.d.ts.map

package/output/app/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../source/app/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAsBxD,qBAAa,SAAU,SAAQ,KAAK;aASC,IAAI,EAAE,MAAM;aAAkB,OAAO,CAAC,EAAE,YAAY;IARvF,4CAA4C;IAC5C,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS;IAI7C,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAG,GAAG,CAAS;gBAEK,IAAI,EAAE,MAAM,EAAkB,OAAO,CAAC,EAAE,YAAY,YAAA,EAAE,OAAO,SAAK;CAKtG;AAED,qBAAa,WAAY,SAAQ,KAAK;aASD,IAAI,EAAE,MAAM;aAAkB,OAAO,CAAC,EAAE,YAAY;IARvF,4CAA4C;IAC5C,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW;IAI/C,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAG,GAAG,CAAS;gBAEK,IAAI,EAAE,MAAM,EAAkB,OAAO,CAAC,EAAE,YAAY,YAAA,EAAE,OAAO,SAAK;CAKtG"}

package/output/app/errors.js

@@ -1,51 +0,0 @@
-/**
- * 错误契约（N2 §2.12）。
- *
- * 框架直接提供并导出 `UserError` / `SystemError`：
- * - `status` 是**字面量**（`400` / `500`）—— 映射表写成
- *   `Record<UserError['status'] | SystemError['status'], number>` 时若改错直接编译失败；
- * - `is()` 是**类型守卫**，走 `Symbol.for` 品牌（**不用 `instanceof`**：跨包 / 编译后 / 原型链丢失
- *   都仍然可靠）；品牌与 `@taicode/common-base` 同名，故基座抛出的同类错误同样被识别；
- * - 业务只抛这两个错误，状态码映射由框架固定（`UserError`→400 / `SystemError`→500）。
- *
- * 构造签名保持 `(code, context?, message?)`。
- */
-const USER_ERROR_BRAND = Symbol.for('@taicode/common/UserError');
-const SYSTEM_ERROR_BRAND = Symbol.for('@taicode/common/SystemError');
-function hasBrand(value, brand) {
-    return typeof value === 'object' && value !== null && value[brand] === true;
-}
-export class UserError extends Error {
-    type;
-    context;
-    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
-    static is(value) {
-        return hasBrand(value, USER_ERROR_BRAND);
-    }
-    /** 固定 HTTP 状态（字面量类型） */
-    status = 400;
-    constructor(type, context, message = '') {
-        super(message, context);
-        this.type = type;
-        this.context = context;
-        this.name = 'UserError';
-        Object.defineProperty(this, USER_ERROR_BRAND, { value: true });
-    }
-}
-export class SystemError extends Error {
-    type;
-    context;
-    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
-    static is(value) {
-        return hasBrand(value, SYSTEM_ERROR_BRAND);
-    }
-    /** 固定 HTTP 状态（字面量类型） */
-    status = 500;
-    constructor(type, context, message = '') {
-        super(message, context);
-        this.type = type;
-        this.context = context;
-        this.name = 'SystemError';
-        Object.defineProperty(this, SYSTEM_ERROR_BRAND, { value: true });
-    }
-}

package/output/app/generate-openapi.test.d.ts

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

package/output/app/generate-openapi.test.d.ts.map

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

package/output/app/generate-openapi.test.js

@@ -1,123 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { z } from 'zod';
-import { defineServer, generateOpenApi, startServer } from './entries.js';
-import { createRedis } from './redis.js';
-/**
- * `generateOpenApi()` 红线。
- *
- * 全程**不得要求配置有效**：不跑 `config` 槽位、不要求 `DATABASE_URL` / `REDIS_URL` 有效、不建连；
- * `resources`（只构造不建连）/ `services` / 中间件注册 / 路由注册照常执行。
- * 跳过集：`config` / `initLifecycleUnits` / `listen`。
- */
-const routeSchema = {
-    querystring: z.object({ name: z.string().optional() }),
-};
-describe('generateOpenApi 红线', () => {
-    it('不跑 config、不要求 DATABASE_URL / REDIS_URL，能出 spec', async () => {
-        delete process.env.DATABASE_URL;
-        delete process.env.REDIS_URL;
-        let configCalls = 0;
-        const server = defineServer({
-            app: { service: 'openapi-test', title: 'OpenAPI Test', version: '1.2.3' },
-            resources: () => ({ database: { connected: false } }),
-            config: () => {
-                configCalls += 1;
-                return {};
-            },
-            services: () => ({}),
-            middlewares: () => [],
-            routers: (ctx) => {
-                ctx.app.get('/widgets', { schema: routeSchema }, () => []);
-            },
-        });
-        const spec = (await generateOpenApi(server));
-        expect(configCalls).toBe(0);
-        expect(spec.openapi).toBe('3.0.3');
-        expect(spec.info).toMatchObject({ title: 'OpenAPI Test', version: '1.2.3' });
-        // 身份块只有 service / title / version：`info.description` 不再由框架填
-        expect(spec.info?.description).toBeUndefined();
-        expect(spec.servers).toEqual([{ url: '/' }]);
-        expect(Object.keys(spec.paths ?? {})).toContain('/widgets');
-        expect(Object.keys(spec.components?.securitySchemes ?? {})).toContain('bearerAuth');
-    });
-    it('跳过集：不跑 config / initLifecycleUnits（但跑 resources / services / 中间件注册 / routers）', async () => {
-        const calls = [];
-        const server = defineServer({
-            app: { service: 'openapi-skip-set', title: 'OpenAPI Skip Set', version: '1.0.0' },
-            resources: () => {
-                calls.push('resources');
-                return {};
-            },
-            config: () => {
-                calls.push('config');
-                return {};
-            },
-            services: () => {
-                calls.push('services');
-                return {
-                    a: {
-                        init: () => {
-                            calls.push('init:a');
-                        },
-                    },
-                };
-            },
-            middlewares: () => [
-                {
-                    name: 'probe',
-                    register: () => {
-                        calls.push('register:probe');
-                    },
-                },
-            ],
-            routers: () => {
-                calls.push('routers');
-            },
-        });
-        await generateOpenApi(server);
-        expect(calls).toEqual(['resources', 'services', 'register:probe', 'routers']);
-    });
-    it('REDIS_URL 存在时仍不建连（惰性包装）', async () => {
-        process.env.REDIS_URL = 'redis://127.0.0.1:1/0';
-        try {
-            const server = defineServer({
-                app: { service: 'openapi-redis-lazy', title: 'Redis Lazy', version: '1.0.0' },
-                // resources 里照常构造 Redis 句柄（惰性包装：不建连、不 ping）
-                resources: (ctx) => ({ redis: createRedis(ctx.env, ctx.log) }),
-                config: () => ({}),
-                services: () => ({}),
-                middlewares: () => [],
-                routers: () => undefined,
-            });
-            const spec = (await generateOpenApi(server));
-            expect(spec.openapi).toBe('3.0.3');
-        }
-        finally {
-            delete process.env.REDIS_URL;
-        }
-    });
-});
-describe('startServer 与 generateOpenApi 共用同一份定义', () => {
-    it('startServer(server, { listen: false }) 返回原生实例、可 inject，且会跑 config', async () => {
-        let configCalls = 0;
-        const server = defineServer({
-            app: { service: 'openapi-shared-definition', title: 'Shared Definition', version: '1.0.0' },
-            resources: () => ({}),
-            config: () => {
-                configCalls += 1;
-                return {};
-            },
-            services: () => ({}),
-            middlewares: () => [],
-            routers: (ctx) => {
-                ctx.app.get('/ping', () => ({ pong: true }));
-            },
-        });
-        const app = await startServer(server, { listen: false });
-        expect(typeof app.inject).toBe('function');
-        const response = await app.inject({ method: 'GET', url: '/ping' });
-        expect(response.statusCode).toBe(200);
-        expect(configCalls).toBe(1);
-        await app.close();
-    });
-});

package/output/app/lifecycle-logging.test.d.ts

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

package/output/app/lifecycle-logging.test.d.ts.map

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