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

package/output/app/shutdown.test.js

@@ -1,103 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { defineServer, startServer } from './entries.js';
-import { runShutdown, SHUTDOWN_ORDER } from './shutdown.js';
-function createShutdownLog() {
-    const entries = [];
-    return { entries, log: { error: (obj, msg) => void entries.push({ obj, msg }) } };
-}
-function createRecordingHandles(record, throwOn) {
-    const step = (name) => () => {
-        record.push(name);
-        if (name === throwOn) {
-            throw new Error(`boom:${name}`);
-        }
-    };
-    return {
-        stopProducers: step('stopProducers'),
-        disposeServices: step('disposeServices'),
-    };
-}
-describe('SHUTDOWN_ORDER', () => {
-    it('固定两步且顺序不可变', () => {
-        expect(SHUTDOWN_ORDER).toEqual(['stopProducers', 'disposeServices']);
-    });
-});
-describe('runShutdown', () => {
-    it('按固定序执行全部步骤', async () => {
-        const record = [];
-        const { log } = createShutdownLog();
-        await runShutdown(createRecordingHandles(record), log);
-        expect(record).toEqual([...SHUTDOWN_ORDER]);
-    });
-    it('单步抛错不阻断后续，并聚合上报', async () => {
-        const record = [];
-        const { entries, log } = createShutdownLog();
-        await runShutdown(createRecordingHandles(record, 'stopProducers'), log);
-        expect(record).toEqual([...SHUTDOWN_ORDER]);
-        const aggregate = entries.find((entry) => entry.msg === '[shutdown] completed with errors');
-        expect(aggregate).toBeDefined();
-        const payload = aggregate?.obj;
-        expect(payload.count).toBe(1);
-        expect(payload.errors).toHaveLength(1);
-    });
-});
-describe('关闭流程集成', () => {
-    it('默认两步按序执行：disposer → services 逆序', async () => {
-        const calls = [];
-        const server = defineServer({
-            app: { service: 'shutdown-integration', title: 'Shutdown Integration', version: '1.0.0' },
-            resources: () => ({ database: { dispose: () => calls.push('disposeResource') } }),
-            config: () => ({}),
-            services: (ctx) => {
-                ctx.disposer.add(() => {
-                    calls.push('stopProducers');
-                });
-                return {
-                    a: {
-                        dispose: () => {
-                            calls.push('disposeServiceA');
-                        },
-                    },
-                    b: {
-                        dispose: () => {
-                            calls.push('disposeServiceB');
-                        },
-                    },
-                };
-            },
-            middlewares: () => [],
-            routers: () => undefined,
-        });
-        const app = await startServer(server, { listen: false });
-        await app.close();
-        // 资源不在生命周期内（框架只管 services）
-        expect(calls).toEqual(['stopProducers', 'disposeServiceB', 'disposeServiceA']);
-    });
-    it('StartServerOptions.shutdown 整体覆盖默认关闭流程', async () => {
-        const calls = [];
-        const server = defineServer({
-            app: { service: 'shutdown-override', title: 'Shutdown Override', version: '1.0.0' },
-            resources: () => ({}),
-            config: () => ({}),
-            services: () => ({
-                a: {
-                    dispose: () => {
-                        calls.push('default-dispose');
-                    },
-                },
-            }),
-            middlewares: () => [],
-            routers: () => undefined,
-        });
-        const app = await startServer(server, {
-            listen: false,
-            shutdown: async (ctx) => {
-                expect(ctx.app).toBeDefined();
-                expect(ctx.services).toBeDefined();
-                calls.push('custom');
-            },
-        });
-        await app.close();
-        expect(calls).toEqual(['custom']);
-    });
-});

package/output/app/signal.d.ts

@@ -1,12 +0,0 @@
-import type { LoggerLike } from './types.js';
-import type { FastifyInstance } from 'fastify';
-/**
- * 内置信号处理（设计 §7.1 `activate` 尾部 / §7.2）。
- *
- * `SIGTERM` / `SIGINT` / `uncaughtException` / `unhandledRejection` ⇒ `app.close()`（触发 `onClose`
- * 的关闭 6 步）⇒ `process.exit(0/1)`。**仅 `listen: true` 时装信号处理**。
- *
- * @returns detach 函数（移除本次注册的监听器）
- */
-export declare function attachSignalHandlers(app: FastifyInstance, log: LoggerLike): () => void;
-//# sourceMappingURL=signal.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../source/app/signal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,IAAI,CA2CtF"}

package/output/app/smoke.test.d.ts

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

package/output/app/smoke.test.d.ts.map

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

package/output/app/smoke.test.js

@@ -1,210 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { z } from 'zod';
-import { defineServer, generateOpenApi, startServer } from './entries.js';
-import { SystemError, UserError } from './errors.js';
-import { defaultMiddlewares } from './middleware/index.js';
-import { createCache, createRedis } from './redis.js';
-const summarySchema = {
-    querystring: z.object({ currency: z.string().optional() }),
-    response: {
-        200: z.object({
-            status: z.string(),
-            message: z.string(),
-            data: z.object({ siteName: z.string(), currency: z.string() }),
-        }),
-    },
-};
-describe('端到端冒烟：defineServer → startServer → inject → generateOpenApi', () => {
-    it('真实装配路径跑通最小服务器（无 Postgres / 无 Redis / 无网络）', async () => {
-        const previousDatabaseUrl = process.env.DATABASE_URL;
-        const previousRedisUrl = process.env.REDIS_URL;
-        delete process.env.DATABASE_URL;
-        delete process.env.REDIS_URL;
-        const lifecycleEvents = [];
-        const counters = { readConfiguration: 0, disposeDatabase: 0 };
-        const database = {
-            readSystemConfiguration: async () => {
-                counters.readConfiguration += 1;
-                return { siteName: 'taicode-smoke', currency: 'CNY' };
-            },
-        };
-        try {
-            const server = defineServer({
-                app: { service: 'smoke', title: 'Smoke Service', version: '1.4.0' },
-                resources: (ctx) => {
-                    const redis = createRedis(ctx.env, ctx.log);
-                    return {
-                        // 构造但不建连；出 spec 路径也会构造
-                        database,
-                        redis,
-                        cache: createCache({ env: ctx.env, prefix: 'smoke', redis, log: ctx.log }),
-                    };
-                },
-                config: async ({ resources }) => {
-                    const configuration = await resources.database.readSystemConfiguration();
-                    return { siteName: configuration.siteName, currency: configuration.currency };
-                },
-                // 声明序即启动序（services 之间不得相互依赖）
-                services: (ctx) => {
-                    return {
-                        // routers 拿不到 resources / config，只能穿过 service
-                        // 配置一律在**调用期**现读：构造期不得读配置（出 spec 路径不跑 config 槽位）
-                        configuration: {
-                            readSiteName: () => ctx.config.siteName,
-                            readCurrency: () => ctx.config.currency,
-                        },
-                        ledger: {
-                            init: () => {
-                                lifecycleEvents.push('init:ledger');
-                            },
-                            dispose: () => {
-                                lifecycleEvents.push('dispose:ledger');
-                            },
-                        },
-                        repository: {
-                            init: () => {
-                                lifecycleEvents.push('init:repository');
-                            },
-                            dispose: () => {
-                                lifecycleEvents.push('dispose:repository');
-                            },
-                        },
-                        mailer: {
-                            init: () => {
-                                lifecycleEvents.push('init:mailer');
-                            },
-                            dispose: () => {
-                                lifecycleEvents.push('dispose:mailer');
-                            },
-                        },
-                        databaseLifecycle: {
-                            dispose: () => {
-                                counters.disposeDatabase += 1;
-                            },
-                        },
-                    };
-                },
-                // 默认预设 [cors, context, auth]
-                middlewares: (ctx) => defaultMiddlewares(ctx),
-                routers: (ctx) => {
-                    ctx.app.get('/ledger/summary', { schema: summarySchema }, () => ({
-                        siteName: ctx.services.configuration.readSiteName(),
-                        currency: ctx.services.configuration.readCurrency(),
-                    }));
-                    ctx.app.get('/ledger/invalid-token', () => {
-                        throw new UserError('INVALID_TOKEN', undefined, '令牌无效或已过期');
-                    });
-                    ctx.app.get('/ledger/database-down', () => {
-                        throw new SystemError('DATABASE_UNAVAILABLE', undefined, '数据库暂不可用');
-                    });
-                },
-            });
-            const app = await startServer(server, { listen: false });
-            // ── 装配期：声明序 init ────────────────────────────────────────────
-            expect(lifecycleEvents).toEqual(['init:ledger', 'init:repository', 'init:mailer']);
-            expect(counters.readConfiguration).toBe(1);
-            try {
-                // ── 业务路由：成功信封 ────────────────────────────────────────────
-                const summaryResponse = await app.inject({
-                    method: 'GET',
-                    url: '/ledger/summary?currency=CNY',
-                    headers: { 'x-request-id': 'smoke-summary-1' },
-                });
-                expect(summaryResponse.statusCode).toBe(200);
-                expect(summaryResponse.json()).toEqual({
-                    status: 'SUCCESS',
-                    message: 'ok',
-                    data: { siteName: 'taicode-smoke', currency: 'CNY' },
-                });
-                expect(summaryResponse.headers['x-request-id']).toBe('smoke-summary-1');
-                // ── UserError → 400 ───────────────────────────────────────────────
-                const userErrorResponse = await app.inject({ method: 'GET', url: '/ledger/invalid-token' });
-                expect(userErrorResponse.statusCode).toBe(400);
-                expect(userErrorResponse.json()).toEqual({
-                    status: 'INVALID_TOKEN',
-                    message: '令牌无效或已过期',
-                    data: null,
-                });
-                // ── SystemError → 500 ─────────────────────────────────────────────
-                const systemErrorResponse = await app.inject({ method: 'GET', url: '/ledger/database-down' });
-                expect(systemErrorResponse.statusCode).toBe(500);
-                expect(systemErrorResponse.json()).toEqual({
-                    status: 'DATABASE_UNAVAILABLE',
-                    message: '数据库暂不可用',
-                    data: null,
-                });
-                // ── 未匹配路由 → 404 ──────────────────────────────────────────────
-                const notFoundResponse = await app.inject({ method: 'GET', url: '/no-such-route' });
-                expect(notFoundResponse.statusCode).toBe(404);
-                expect(notFoundResponse.json()).toMatchObject({ status: 'NOT_IMPLEMENTED', data: null });
-                expect(notFoundResponse.headers['x-request-id']).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
-                expect(notFoundResponse.json()).not.toHaveProperty('requestId');
-            }
-            finally {
-                await app.close();
-            }
-            // ── 关闭：services 逆序 dispose ─────────────────────────────────────
-            expect(lifecycleEvents).toEqual([
-                'init:ledger',
-                'init:repository',
-                'init:mailer',
-                'dispose:mailer',
-                'dispose:repository',
-                'dispose:ledger',
-            ]);
-            expect(counters.disposeDatabase).toBe(1);
-            // ── 同一份定义 → generateOpenApi：不跑 config、不重跑 init ──────────
-            const spec = (await generateOpenApi(server));
-            expect(counters.readConfiguration).toBe(1);
-            expect(lifecycleEvents).toHaveLength(6);
-            expect(spec.openapi).toBe('3.0.3');
-            expect(spec.info).toMatchObject({ title: 'Smoke Service', version: '1.4.0' });
-            expect(Object.keys(spec.paths ?? {})).toEqual(expect.arrayContaining(['/ledger/summary', '/ledger/invalid-token', '/ledger/database-down']));
-        }
-        finally {
-            if (previousDatabaseUrl === undefined) {
-                delete process.env.DATABASE_URL;
-            }
-            else {
-                process.env.DATABASE_URL = previousDatabaseUrl;
-            }
-            if (previousRedisUrl === undefined) {
-                delete process.env.REDIS_URL;
-            }
-            else {
-                process.env.REDIS_URL = previousRedisUrl;
-            }
-        }
-    });
-    it('非预置原生插件可在 routers(ctx) 里经 ctx.app.register() 注册并生效', async () => {
-        const smokeDecoratorPlugin = async (app) => {
-            app.decorate('smokeDecorator', () => 'smoke-decorated');
-            app.get('/plugin/decorated', () => ({
-                value: app.smokeDecorator(),
-            }));
-        };
-        const server = defineServer({
-            app: { service: 'smoke-plugin', title: 'Smoke Plugin', version: '1.0.0' },
-            resources: () => ({}),
-            config: () => ({}),
-            services: () => ({}),
-            middlewares: () => [],
-            routers: (ctx) => {
-                void ctx.app.register(smokeDecoratorPlugin);
-            },
-        });
-        const app = await startServer(server, { listen: false });
-        try {
-            const response = await app.inject({ method: 'GET', url: '/plugin/decorated' });
-            expect(response.statusCode).toBe(200);
-            expect(response.json()).toEqual({
-                status: 'SUCCESS',
-                message: 'ok',
-                data: { value: 'smoke-decorated' },
-            });
-        }
-        finally {
-            await app.close();
-        }
-    });
-});

package/output/app/test-support.d.ts

@@ -1,21 +0,0 @@
-import type { ConfigEnv } from './env.js';
-import type { LoggerLike } from './types.js';
-/**
- * 测试公共助手（仅测试使用）。
- *
- * 只放「多个测试文件都要用」的小工具：记录型 logger、测试用 env。
- * 断言与业务语义一律写在各自 `*.test.ts` 内，避免助手文件成为第二真相源。
- */
-export interface LogEntry {
-    level: 'debug' | 'info' | 'warn' | 'error';
-    obj: unknown;
-    msg?: string;
-}
-/** 记录型 logger：满足 `LoggerLike`，便于断言「被调用了 / 在什么级别」 */
-export interface RecordingLogger extends LoggerLike {
-    readonly entries: LogEntry[];
-}
-export declare function createRecordingLogger(): RecordingLogger;
-/** 测试用 `ConfigEnv`（固定读取约定：`ENV` / `API_PORT` / `LOG_LEVEL` / `DATABASE_URL` / `REDIS_URL`） */
-export declare function createTestConfigEnv(overrides?: Partial<ConfigEnv>): ConfigEnv;
-//# sourceMappingURL=test-support.d.ts.map

package/output/app/test-support.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"test-support.d.ts","sourceRoot":"","sources":["../../source/app/test-support.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;;GAKG;AAEH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;IAC1C,GAAG,EAAE,OAAO,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,oDAAoD;AACpD,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,QAAQ,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAA;CAC7B;AAED,wBAAgB,qBAAqB,IAAI,eAAe,CAcvD;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,SAAS,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CASjF"}

package/output/app/test-support.js

@@ -1,24 +0,0 @@
-export function createRecordingLogger() {
-    const entries = [];
-    const record = (level) => (obj, msg) => {
-        entries.push({ level, obj, msg });
-    };
-    return {
-        entries,
-        debug: record('debug'),
-        info: record('info'),
-        warn: record('warn'),
-        error: record('error'),
-    };
-}
-/** 测试用 `ConfigEnv`（固定读取约定：`ENV` / `API_PORT` / `LOG_LEVEL` / `DATABASE_URL` / `REDIS_URL`） */
-export function createTestConfigEnv(overrides = {}) {
-    return {
-        ENV: 'test',
-        API_PORT: '',
-        LOG_LEVEL: 'info',
-        DATABASE_URL: '',
-        REDIS_URL: undefined,
-        ...overrides,
-    };
-}

package/output/app/type-augment.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"type-augment.d.ts","sourceRoot":"","sources":["../../source/app/type-augment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEzD,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,kBAAkB,GAAG,sBAAsB,CAAA;AAE3F,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,cAAc;IACd,MAAM,EAAE,MAAM,CAAA;IACd,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,OAAO,QAAQ,SAAS,CAAC;IACvB,UAAU,cAAc;QACtB,wBAAwB;QACxB,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,wBAAwB;QACxB,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,4CAA4C;QAC5C,GAAG,CAAC,EAAE,cAAc,CAAA;KACrB;IAED,UAAU,oBAAoB;QAC5B,+EAA+E;QAC/E,cAAc,CAAC,EAAE,aAAa,EAAE,CAAA;QAChC,cAAc;QACd,SAAS,CAAC,EAAE,aAAa,CAAA;KAC1B;CACF"}

package/output/app/types.d.ts

@@ -1,228 +0,0 @@
-import type { Disposer } from '@taicode/common-base';
-import type { FastifyBaseLogger, FastifyInstance, RawServerDefault } from 'fastify';
-import type { ZodTypeProvider } from 'fastify-type-provider-zod';
-import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { ConfigEnv } from './env.js';
-import type { SystemError } from './errors.js';
-/**
- * `defineServer` 槽位口径与接口类型（N1 / N2，**唯一规格来源**）。
- *
- * 顶层是「一个身份块 + 五个工厂槽位」，**键顺序即分层**：
- *
- * ```
- * app            （身份块，无依赖）
- * resources      ← env                     引导期：唯一读 env 的地方
- * config         ← env + resources         引导期：❗不给 services（结构性解耦）
- * services       ← resources + config      运行期开始：❗不给 env、不给 services
- * middlewares    ← app + services + config （不给 resources / env）
- * routers        ← app + services          （不给 resources / env / config）
- * ```
- *
- * 槽位只能引用**排在它前面**的产物（向下引用是编译错误）；`env` 只属引导期
- * （`resources` / `config` 可见，运行期三层一律看不到）。
- *
- * 类型安全机制（N2 §1）：
- * - **M1 分阶段 ctx**：每个工厂只拿到「该阶段该看的字段」；
- * - **M2 `Awaited<>` 归一**：工厂签名写 `(ctx) => R`（不是 `R | Promise<R>`），下游一律
- *   `Awaited<R>` / `Awaited<C>` / `Awaited<S>`；
- * - **M3 资源嵌套**：资源包挂在 `ctx.resources` 上（不再摊平到 ctx，键冲突从根上消失）；
- * - **M4 `Live<T>` 静态开关**：资源包里值为 `false` 的键在类型上剔除；
- * - **M5 强类型 `services`**：`middlewares` / `routers` 的 `ctx.services` 是 `S` 实体；
- * - **M6 品牌 + 类型守卫**：`Server` 带品牌，`isServer()` 收窄；
- * - **M7 负向类型测试**：`define-server.negative-cases.ts`，由 `tsc --noEmit` 覆盖。
- *
- * 命名全拼：`requestId` / `database` / `configuration` / `service`（不用 `db` / `cfg`）。
- */
-/** 骨架只按 `(obj, msg)` 形态打日志；`app.log` 与 `@taicode/common-base` 的 `Logger` 都满足 */
-export interface LoggerLike {
-    debug: (obj: unknown, msg?: string) => void;
-    info: (obj: unknown, msg?: string) => void;
-    warn: (obj: unknown, msg?: string) => void;
-    error: (obj: unknown, msg?: string) => void;
-}
-/** 同步或异步（`Awaited<>` 归一的原料） */
-export type MaybePromise<T> = T | Promise<T>;
-/**
- * 路由级类型安全的载体：带 `ZodTypeProvider` 的 `FastifyInstance`。
- *
- * 裸 `FastifyInstance` 会让路由的 `params` / `body` / `query` 全是 `unknown`；带上 provider 后
- * `request.params.id` 有类型。
- */
-export type AppInstance = FastifyInstance<RawServerDefault, IncomingMessage, ServerResponse, FastifyBaseLogger, ZodTypeProvider>;
-/**
- * 身份块：非 env 派生，出 spec 路径也要用。
- *
- * `version` **必填、无默认值**（缺它就是编译错误，杜绝「悄悄兜底成 1.0.0」）。
- */
-export interface AppIdentity {
-    /** 权限注册键 / cache 前缀 / 失效通道前缀 / 日志标签 */
-    readonly service: string;
-    readonly title: string;
-    /** openapi `info.version` + 权限操作自注册；建议从 package.json 读入 */
-    readonly version: string;
-}
-/**
- * Redis 句柄（惰性包装）。
- *
- * 框架**不操作** Redis 命令，只持有并在关闭时透传 dispose；构造时不建连、不 ping。
- * 因此保持开放类型，各仓注入自己的客户端实现不受约束。
- */
-export interface RedisHandle {
-    client: unknown;
-    dispose: () => void | Promise<void>;
-}
-/**
- * 剔掉值为 `false` 的键（编译期静态开关）。
- *
- * 资源包里写 `cache: false` 表示**静态关闭**：`Live<T>` 里该键**不存在**，访问直接编译失败；
- * 而 `cache: Cache | undefined`（显式可选）表示**运行时缺省**：键存在，类型为 `Cache | undefined`。
- */
-export type Live<T> = {
-    [K in keyof T as T[K] extends false ? never : K]: T[K];
-};
-/** 框架在 ctx 上暴露的资源视图（`Awaited<>` 归一 + `false` 键剔除） */
-export type ResourcesView<R> = Live<Awaited<R>>;
-/**
- * 资源错误分类器（响应层用）。
- *
- * **每个资源注册自己的分类器**（一个资源一个）：只认领自己错误域内的错误，认领不了返回 `null` 交给
- * 下一个。由服务仓在 `resources(ctx)` 里通过 `ctx.registerClassifyError(...)` 注册；可注册多个，
- * 按注册顺序求值取第一个非 `null` 的结果；全部未命中 / 一个都没注册 → 响应层落 `UNKNOWN_ERROR` 兜底。
- */
-export type ErrorClassifier = (error: unknown) => SystemError | null;
-/**
- * `resources(ctx)` 的入参：**只有 `env` + `log`**（外加槽位专属的注册能力）。
- *
- * 结构上排除 `config` / `services` / `app` → 「资源依赖配置」这类循环**编译期写不出来**。
- */
-export interface ResourcesContext {
-    readonly env: ConfigEnv;
-    readonly log: LoggerLike;
-    /**
-     * **每个资源注册自己的错误分类器**（响应层用）。
-     *
-     * 一个资源一个分类器，各管各的错误域：只认领自己域内的错误，认领不了返回 `null` 交给下一个。
-     * 可注册多个：按注册顺序求值，取第一个非 `null` 的结果；全部未命中 → 响应层落 `UNKNOWN_ERROR` 兜底。
-     * 本方法是 **resources 槽位专属能力**（其他槽位的 ctx 不提供）。
-     */
-    registerClassifyError(classifier: ErrorClassifier): void;
-}
-export type ResourcesFactory<R> = (ctx: ResourcesContext) => R;
-/**
- * `config(ctx)` 的入参：`env` + `log` + 资源视图。
- *
- * **没有** `services`（此时尚未构造）/ `app`（此时尚未装配）。
- */
-export interface ConfigContext<R> {
-    readonly env: ConfigEnv;
-    readonly log: LoggerLike;
-    readonly resources: ResourcesView<R>;
-}
-export type ConfigFactory<R, C> = (ctx: ConfigContext<R>) => C;
-/**
- * 一个 service 值：可选实现 `init` / `dispose`。
- *
- * **没有 `name` / `dependsOn`**：名字用对象键，依赖不存在（`services` ctx 没有 `services` 字段，
- * 编译期禁止互依）。顺序语义只有一条：按**对象声明序** `init` / **逆序** `dispose`。
- */
-export interface ServiceUnit {
-    init?(): void | Promise<void>;
-    dispose?(): void | Promise<void>;
-}
-/**
- * `services(ctx)` 的入参：`log` + `disposer` + `resources` + `config`。
- *
- * ❗**故意没有 `env`**（服务层属运行期，不得读 env）；❗**故意没有 `services`**（禁 service 互依）。
- */
-export interface ServiceContext<R, C> {
-    readonly log: LoggerLike;
-    readonly disposer: Disposer;
-    readonly resources: ResourcesView<R>;
-    readonly config: Awaited<C>;
-}
-export type ServicesFactory<R, C, S> = (ctx: ServiceContext<R, C>) => S;
-/**
- * 中间件单元：一个注册函数（`register(app)`），按**数组序**注册。
- *
- * `name` 仅用于报错定位 / 日志跟踪；**不参与生命周期**（要常驻资源就放 `services`）。
- */
-export interface MiddlewareUnit {
-    readonly name?: string;
-    register(app: AppInstance): void | Promise<void>;
-}
-/**
- * `middlewares(ctx)` 的入参：`app` + `log` + `services` + `config`。
- *
- * ❗**故意没有 `resources` / `env`** —— 中间件要访问数据层必须穿过 service。
- */
-export interface MiddlewareContext<C, S> {
-    readonly app: AppInstance;
-    readonly log: LoggerLike;
-    readonly services: Awaited<S>;
-    readonly config: Awaited<C>;
-}
-export type MiddlewaresFactory<C, S> = (ctx: MiddlewareContext<C, S>) => MiddlewareUnit[];
-/**
- * `routers(ctx)` 的入参：`app` + `log` + `services`。
- *
- * ❗**故意没有 `resources` / `env` / `config`** —— 路由**只能穿过 service**，绕不过层直连数据层。
- */
-export interface RouterContext<S> {
-    readonly app: AppInstance;
-    readonly log: LoggerLike;
-    readonly services: Awaited<S>;
-}
-export type RoutersFactory<S> = (ctx: RouterContext<S>) => void | Promise<void>;
-/**
- * 若某个 service 值声明了 `dependsOn`，该值类型塌成 `never` → 赋值报错。
- */
-export type AssertNoDependencies<S> = {
-    [K in keyof S]: S[K] extends {
-        dependsOn: unknown;
-    } ? never : S[K];
-};
-/**
- * `services` 返回值形状闸门：
- * - 原始类型值（`string` / `number` / `boolean`）**拒绝**（防把配置塞进 services）；
- * - 声明了 `dependsOn` 的值**拒绝**（禁 service 互依）。
- */
-export type ServicesShape<S> = {
-    [K in keyof S]: S[K] extends string | number | boolean ? never : S[K] extends {
-        dependsOn: unknown;
-    } ? never : S[K];
-};
-/**
- * `defineServer()` 入参：一个身份块 + 五个工厂槽位（键顺序=分层）。
- *
- * `S` 上的两道闸门（`ServicesShape<S>`，N2 §2.5）写在 `services` 的返回类型上：
- * `S & ServicesShape<S>` —— 形状合法时恒等，非法时该值塌成 `never` → 编译失败。
- */
-export interface ServerConfig<R, C, S> {
-    app: AppIdentity;
-    resources: ResourcesFactory<R>;
-    config: ConfigFactory<NoInfer<R>, C>;
-    services: (ctx: ServiceContext<NoInfer<R>, NoInfer<C>>) => S & ServicesShape<S>;
-    middlewares: MiddlewaresFactory<NoInfer<C>, NoInfer<S>>;
-    routers: RoutersFactory<NoInfer<S>>;
-}
-/** 品牌字段值（`Server` 的 `__brand`） */
-export declare const SERVER_BRAND = "taicode.server";
-/** 纯定义产物：同一份定义可同时喂给「启动」与「出 spec」 */
-export type Server<R, C, S> = ServerConfig<R, C, S> & {
-    readonly __brand: typeof SERVER_BRAND;
-};
-/** `startServer()` 的逃生选项 */
-export interface StartServerOptions<R = unknown, C = unknown, S = unknown> {
-    /** 是否 listen + 装信号；默认 `NODE_ENV !== 'test'` */
-    listen?: boolean;
-    /** 整体覆盖关闭流程 */
-    shutdown?: (ctx: ShutdownContext<R, C, S>) => Promise<void>;
-}
-/** 关闭阶段视图：`services` ctx + `app` + `services` 实体 */
-export interface ShutdownContext<R, C, S> extends ServiceContext<R, C> {
-    readonly app: AppInstance;
-    readonly services: Awaited<S>;
-}
-/** `generateOpenApi()` 的返回（OpenAPI 文档对象） */
-export type OpenApiDocument = Record<string, unknown>;
-//# sourceMappingURL=types.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../source/app/types.ts"],"names":[],"mappings":"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"}

package/output/context/index.d.ts

@@ -1,6 +0,0 @@
-import type { FastifyBaseLogger, FastifyRequest } from 'fastify';
-export interface RequestContext {
-    log: FastifyBaseLogger;
-}
-export declare function createContext(request: FastifyRequest): RequestContext;
-//# sourceMappingURL=index.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEhE,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,iBAAiB,CAAA;CACvB;AAcD,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAErE"}

package/output/context/index.js

@@ -1,14 +0,0 @@
-const fallbackLogger = {
-    trace: () => { },
-    debug: () => { },
-    info: () => { },
-    warn: () => { },
-    error: () => { },
-    fatal: () => { },
-    child: () => fallbackLogger,
-    level: 'info',
-    silent: () => { },
-};
-export function createContext(request) {
-    return { log: request.log || fallbackLogger };
-}