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

package/output/app/signal.js

@@ -0,0 +1,45 @@
+/**
+ * 内置信号处理（设计 §7.1 `activate` 尾部 / §7.2）。
+ *
+ * `SIGTERM` / `SIGINT` / `uncaughtException` / `unhandledRejection` ⇒ `app.close()`（触发 `onClose`
+ * 的关闭 6 步）⇒ `process.exit(0/1)`。**仅 `listen: true` 时装信号处理**。
+ *
+ * @returns detach 函数（移除本次注册的监听器）
+ */
+export function attachSignalHandlers(app, log) {
+    let closing = false;
+    const shutdown = (signal, code) => {
+        if (closing) {
+            return;
+        }
+        closing = true;
+        log.info({ signal }, '[server] received shutdown signal');
+        app.close().then(() => {
+            log.info({ signal }, '[server] shutdown complete');
+            process.exit(code);
+        }, (error) => {
+            log.error({ error }, '[server] error during shutdown');
+            process.exit(1);
+        });
+    };
+    const onSigterm = () => shutdown('SIGTERM', 0);
+    const onSigint = () => shutdown('SIGINT', 0);
+    const onUncaught = (error) => {
+        log.error({ error }, '[server] uncaught exception');
+        shutdown('uncaughtException', 1);
+    };
+    const onRejection = (reason) => {
+        log.error({ reason }, '[server] unhandled rejection');
+        shutdown('unhandledRejection', 1);
+    };
+    process.on('SIGTERM', onSigterm);
+    process.on('SIGINT', onSigint);
+    process.on('uncaughtException', onUncaught);
+    process.on('unhandledRejection', onRejection);
+    return () => {
+        process.off('SIGTERM', onSigterm);
+        process.off('SIGINT', onSigint);
+        process.off('uncaughtException', onUncaught);
+        process.off('unhandledRejection', onRejection);
+    };
+}

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

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

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

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

package/output/app/smoke.test.js

@@ -0,0 +1,210 @@
+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

@@ -0,0 +1,21 @@
+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

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

@@ -0,0 +1,24 @@
+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

@@ -0,0 +1,34 @@
+/**
+ * 框架统一提供的类型增强（设计 §8「类型增强」红线）。
+ *
+ * `request.user` / `request.token` / `request.id` 与 `routeOptions.config.accessControls`（以及
+ * 限流规则 `rateLimit`）的 `declare module 'fastify'` 由 common 统一提供，各仓删除自建声明。
+ */
+import type { RequestContext } from '../context/index.js';
+/** 路由级访问控制声明（各服务在 `routeOptions.config.accessControls` 里写） */
+export type AccessControl = 'NoLoginRequired' | 'IgnorePermission' | 'RequiredSecurityCode';
+/** 路由级限流规则（`createRateLimitMiddleware` 消费，另有路由级 `config.rateLimit`） */
+export interface RateLimitRule {
+    limit: number;
+    /** 窗口大小（秒） */
+    window: number;
+    /** 限流键维度，默认 `['ip']` */
+    keys?: string[];
+}
+declare module 'fastify' {
+    interface FastifyRequest {
+        /** 认证后由 `auth` 中间件填充 */
+        user?: unknown;
+        /** 认证后由 `auth` 中间件填充 */
+        token?: unknown;
+        /** `createContextMiddleware()` 注入的请求级上下文 */
+        ctx?: RequestContext;
+    }
+    interface FastifyContextConfig {
+        /** 路由级访问控制（`NoLoginRequired` / `IgnorePermission` / `RequiredSecurityCode`） */
+        accessControls?: AccessControl[];
+        /** 路由级限流规则 */
+        rateLimit?: RateLimitRule;
+    }
+}
+//# sourceMappingURL=type-augment.d.ts.map

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

@@ -0,0 +1 @@
+{"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/type-augment.js

@@ -0,0 +1,7 @@
+/**
+ * 框架统一提供的类型增强（设计 §8「类型增强」红线）。
+ *
+ * `request.user` / `request.token` / `request.id` 与 `routeOptions.config.accessControls`（以及
+ * 限流规则 `rateLimit`）的 `declare module 'fastify'` 由 common 统一提供，各仓删除自建声明。
+ */
+export {};

package/output/app/types.d.ts

@@ -0,0 +1,211 @@
+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';
+/**
+ * `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>>;
+/**
+ * `resources(ctx)` 的入参：**只有 `env` + `log`**。
+ *
+ * 结构上排除 `config` / `services` / `app` → 「资源依赖配置」这类循环**编译期写不出来**。
+ */
+export interface ResourcesContext {
+    readonly env: ConfigEnv;
+    readonly log: LoggerLike;
+}
+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

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

package/output/app/types.js

@@ -0,0 +1,2 @@
+/** 品牌字段值（`Server` 的 `__brand`） */
+export const SERVER_BRAND = 'taicode.server';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taicode/common-server",
-  "version": "3.7.13",
+  "version": "4.0.0-beta.1",
   "author": "Alain",
   "license": "ISC",
   "description": "",
@@ -23,11 +23,19 @@
   "files": [
     "output"
   ],
+  "dependencies": {
+    "@fastify/cookie": "^11",
+    "@fastify/cors": "^11",
+    "@fastify/swagger": "^9",
+    "@scalar/fastify-api-reference": "^1",
+    "dotenv": "^17.3.1",
+    "fastify-type-provider-zod": "^6",
+    "zod": "^4.3.6"
+  },
   "peerDependencies": {
     "fastify": "^5.5.0",
     "redis": "^5.11.0",
-    "zod": "^4.1.0",
-    "@taicode/common-base": "^3.7.13"
+    "@taicode/common-base": "^4.0.0-beta.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.3",
@@ -41,8 +49,7 @@
     "redis": "^5.11.0",
     "typescript-eslint": "^8.56.1",
     "vitest": "^3.2.4",
-    "zod": "^4.3.6",
-    "@taicode/common-base": "^3.7.13"
+    "@taicode/common-base": "^4.0.0-beta.1"
   },
   "scripts": {
     "test": "vitest run",