@taicode/common-server 3.7.13 → 3.8.0

package/output/app/assemble.d.ts

@@ -0,0 +1,16 @@
+import type { DatabaseModule, ModuleAssembly, ModuleName, ServerModule } from './module.js';
+/** 装配结果：注册顺序、按名索引、被 `false` 跳过的名字、以及数据层模块句柄 */
+export interface ResolvedModules {
+    order: ModuleName[];
+    byName: Partial<Record<ModuleName, ServerModule>>;
+    disabled: ModuleName[];
+    database?: DatabaseModule;
+}
+/**
+ * 装配期校验 + 槽位解析（design §3.2）。
+ *
+ * 报错**发生在 `defineServer()` 装配阶段**（返回 promise resolve 之前），不拖到 `listen` 才炸。
+ * 校验顺序：未知名 → 重复 / 键名不符 → 依赖被跳过 / 依赖环 → 未实现模块未显式 false → database 未提供。
+ */
+export declare function assembleModules(assembly?: ModuleAssembly): ResolvedModules;
+//# sourceMappingURL=assemble.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../source/app/assemble.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE3F,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAA;IACjD,QAAQ,EAAE,UAAU,EAAE,CAAA;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B;AA2HD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,eAAe,CAQ1E"}

package/output/app/assemble.js

@@ -0,0 +1,124 @@
+import { createDefaultModules } from './default-modules.js';
+import { MODULE_NAMES, PENDING_MODULES } from './module.js';
+function isModuleName(value) {
+    return MODULE_NAMES.includes(value);
+}
+function assertKnownNames(provided) {
+    for (const key of Object.keys(provided)) {
+        if (!isModuleName(key)) {
+            throw new Error(`Unknown module "${key}". Allowed: ${MODULE_NAMES.join(', ')}`);
+        }
+    }
+}
+function assertNamesMatch(provided) {
+    const seen = new Set();
+    for (const key of Object.keys(provided)) {
+        const value = provided[key];
+        if (value === undefined || value === false) {
+            continue;
+        }
+        if (seen.has(value.name)) {
+            throw new Error(`Module "${value.name}" registered twice`);
+        }
+        if (value.name !== key) {
+            throw new Error(`Module key "${key}" != module.name "${value.name}"`);
+        }
+        seen.add(value.name);
+    }
+}
+function assertNoCycles(provided) {
+    const visiting = new Set();
+    const visited = new Set();
+    function visit(name, path) {
+        if (visited.has(name)) {
+            return;
+        }
+        if (visiting.has(name)) {
+            throw new Error(`Module dependency cycle detected: ${[...path, name].join(' -> ')}`);
+        }
+        visiting.add(name);
+        const value = provided[name];
+        const deps = value === undefined || value === false ? [] : value.dependsOn ?? [];
+        for (const dep of deps) {
+            if (isModuleName(dep)) {
+                visit(dep, [...path, name]);
+            }
+        }
+        visiting.delete(name);
+        visited.add(name);
+    }
+    for (const key of Object.keys(provided)) {
+        if (isModuleName(key)) {
+            visit(key, []);
+        }
+    }
+}
+function assertDependencies(provided) {
+    for (const key of Object.keys(provided)) {
+        const value = provided[key];
+        if (value === undefined || value === false) {
+            continue;
+        }
+        for (const dep of value.dependsOn ?? []) {
+            if (!isModuleName(dep)) {
+                throw new Error(`Module "${value.name}" depends on unknown module "${dep}"`);
+            }
+            if (provided[dep] === false) {
+                throw new Error(`Module "${value.name}" depends on "${dep}" which is disabled`);
+            }
+        }
+    }
+    assertNoCycles(provided);
+}
+function assertPendingProvided(provided) {
+    for (const [name, stage] of Object.entries(PENDING_MODULES)) {
+        if (provided[name] === undefined) {
+            throw new Error(`Module "${name}" is not implemented until ${stage}; pass false to opt out`);
+        }
+    }
+}
+function assertDatabaseProvided(provided) {
+    if (provided.database === undefined) {
+        throw new Error('Module "database" requires createPrismaDatabaseModule({...}) or false');
+    }
+}
+function resolveModules(provided) {
+    const defaults = createDefaultModules();
+    const byName = {};
+    const disabled = [];
+    for (const name of MODULE_NAMES) {
+        const value = provided[name];
+        if (value === false) {
+            disabled.push(name);
+            continue;
+        }
+        if (value) {
+            byName[name] = value;
+            continue;
+        }
+        const fallback = defaults[name];
+        if (fallback) {
+            byName[name] = fallback;
+        }
+    }
+    const order = MODULE_NAMES.filter((name) => byName[name] !== undefined);
+    const candidate = byName.database;
+    // `database` 已由 `assertDatabaseProvided` 强制显式：走到这里要么是 `DatabaseModule`，要么是 `false`
+    const database = typeof candidate?.createClient === 'function' ? candidate : undefined;
+    return { order, byName, disabled, database };
+}
+/**
+ * 装配期校验 + 槽位解析（design §3.2）。
+ *
+ * 报错**发生在 `defineServer()` 装配阶段**（返回 promise resolve 之前），不拖到 `listen` 才炸。
+ * 校验顺序：未知名 → 重复 / 键名不符 → 依赖被跳过 / 依赖环 → 未实现模块未显式 false → database 未提供。
+ */
+export function assembleModules(assembly) {
+    const provided = (assembly ?? {});
+    assertKnownNames(provided);
+    assertNamesMatch(provided);
+    assertDependencies(provided);
+    assertPendingProvided(provided);
+    assertDatabaseProvided(provided);
+    return resolveModules(provided);
+}

package/output/app/database.d.ts

@@ -0,0 +1,36 @@
+import type { DatabaseClientParams, DatabaseModule, PrismaErrorConstructors, PrismaOperationLabels } from './module.js';
+export interface PrismaDatabaseModuleParams<Ctor extends new (...args: never[]) => unknown> {
+    /**
+     * 各仓生成的 client 构造函数（`@prisma/generated/*`）——**只能由各仓经参数注入**，
+     * common 不引用任何具体生成产物（决策 #8）。
+     */
+    PrismaClient: Ctor;
+    /**
+     * 各仓生成的命名空间（`instanceof` 判定用；跨包 `instanceof` 不可靠，决策 #9）。
+     */
+    PrismaNamespace: PrismaErrorConstructors;
+    /** 可选：覆盖 operation 标签；不传则用 common 默认集 */
+    operationLabels?: PrismaOperationLabels;
+    /**
+     * 可选：构造 Prisma client 的参数工厂。
+     *
+     * common **不依赖** `@prisma/client` 与其驱动适配器（如 `@prisma/adapter-pg`），
+     * 由调用方注入构造参数，例如：
+     *
+     * ```ts
+     * createClientArgs: (params) => [
+     *   { adapter: new PrismaPg(params.postgresConfig, { schema: (params.postgresConfig as { schema: string }).schema }) },
+     * ]
+     * ```
+     *
+     * 省略时等价于 `new PrismaClient()`（要求传入的 `PrismaClient` 自身可完成连接）。
+     */
+    createClientArgs?: (params: DatabaseClientParams) => unknown[];
+}
+/**
+ * `database` 模块的默认实现：Prisma（design §3.3 / 调研 D）。
+ *
+ * 返回类型即 `defineServer<Db>` 的 `Db`，调用方据此**推断**类型、无需强转（决策 10-2）。
+ */
+export declare function createPrismaDatabaseModule<Ctor extends new (...args: never[]) => unknown>(params: PrismaDatabaseModuleParams<Ctor>): DatabaseModule<InstanceType<Ctor>>;
+//# sourceMappingURL=database.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../source/app/database.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,cAAc,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAevH,MAAM,WAAW,0BAA0B,CAAC,IAAI,SAAS,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO;IACxF;;;OAGG;IACH,YAAY,EAAE,IAAI,CAAA;IAClB;;OAEG;IACH,eAAe,EAAE,uBAAuB,CAAA;IACxC,yCAAyC;IACzC,eAAe,CAAC,EAAE,qBAAqB,CAAA;IACvC;;;;;;;;;;;;;OAaG;IACH,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,OAAO,EAAE,CAAA;CAC/D;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,SAAS,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,EACvF,MAAM,EAAE,0BAA0B,CAAC,IAAI,CAAC,GACvC,cAAc,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CA2BpC"}

package/output/app/database.js

@@ -0,0 +1,40 @@
+import { SystemError } from '@taicode/common-base';
+/** common 默认的统一 operation 标签（design §2.3：抽进 common 时统一口径） */
+const DEFAULT_OPERATION_LABELS = {
+    known: '已知请求错误',
+    unknown: '未知请求错误',
+    validation: '参数校验错误',
+    initialization: '初始化错误',
+    rustPanic: '引擎崩溃',
+};
+/**
+ * `database` 模块的默认实现：Prisma（design §3.3 / 调研 D）。
+ *
+ * 返回类型即 `defineServer<Db>` 的 `Db`，调用方据此**推断**类型、无需强转（决策 10-2）。
+ */
+export function createPrismaDatabaseModule(params) {
+    const labels = { ...DEFAULT_OPERATION_LABELS, ...params.operationLabels };
+    return {
+        name: 'database',
+        createClient: (clientParams) => {
+            const args = params.createClientArgs ? params.createClientArgs(clientParams) : [];
+            return Reflect.construct(params.PrismaClient, args);
+        },
+        classifyError: (error) => {
+            const hit = (Ctor, label) => (error instanceof Ctor ? label : null);
+            const namespace = params.PrismaNamespace;
+            const label = hit(namespace.PrismaClientKnownRequestError, labels.known) ??
+                hit(namespace.PrismaClientUnknownRequestError, labels.unknown) ??
+                hit(namespace.PrismaClientValidationError, labels.validation) ??
+                hit(namespace.PrismaClientInitializationError, labels.initialization) ??
+                hit(namespace.PrismaClientRustPanicError, labels.rustPanic);
+            return label ? new SystemError('DATABASE_ERROR', { operation: label }, label) : null;
+        },
+        dispose: async (db) => {
+            const target = db;
+            if (typeof target.$disconnect === 'function') {
+                await target.$disconnect();
+            }
+        },
+    };
+}

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

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

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

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

package/output/app/database.test.js

@@ -0,0 +1,66 @@
+import { SystemError } from '@taicode/common-base';
+import { describe, expect, it } from 'vitest';
+import { createPrismaDatabaseModule } from './database.js';
+const TEST_CONFIG = { loadConfig: () => ({ debug: false, port: 0 }) };
+const NAMESPACE = {
+    PrismaClientKnownRequestError: class extends Error {
+    },
+    PrismaClientUnknownRequestError: class extends Error {
+    },
+    PrismaClientValidationError: class extends Error {
+    },
+    PrismaClientInitializationError: class extends Error {
+    },
+    PrismaClientRustPanicError: class extends Error {
+    },
+};
+class Client {
+    static lastArgs = [];
+    disconnected = false;
+    constructor(...args) {
+        Client.lastArgs = args;
+    }
+    async $disconnect() {
+        this.disconnected = true;
+    }
+}
+describe('createPrismaDatabaseModule', () => {
+    it('createClient 使用注入的构造函数与参数工厂（common 不依赖 @prisma/client）', async () => {
+        const database = createPrismaDatabaseModule({
+            PrismaClient: Client,
+            PrismaNamespace: NAMESPACE,
+            createClientArgs: (params) => [{ adapter: params.postgresConfig }],
+        });
+        const client = await database.createClient({ config: TEST_CONFIG, postgresConfig: { schema: 'test' } });
+        expect(client).toBeInstanceOf(Client);
+        expect(Client.lastArgs).toEqual([{ adapter: { schema: 'test' } }]);
+    });
+    it('省略 createClientArgs 时等价于 new PrismaClient()', async () => {
+        const database = createPrismaDatabaseModule({ PrismaClient: Client, PrismaNamespace: NAMESPACE });
+        await database.createClient({ config: TEST_CONFIG, postgresConfig: undefined });
+        expect(Client.lastArgs).toEqual([]);
+    });
+    it('classifyError 命中 5 类错误时返回 SystemError(DATABASE_ERROR)，未命中返回 null', () => {
+        const database = createPrismaDatabaseModule({ PrismaClient: Client, PrismaNamespace: NAMESPACE });
+        const known = database.classifyError(new NAMESPACE.PrismaClientKnownRequestError());
+        expect(SystemError.is(known)).toBe(true);
+        expect(known?.type).toBe('DATABASE_ERROR');
+        expect(known?.context?.operation).toBe('已知请求错误');
+        expect(database.classifyError(new NAMESPACE.PrismaClientRustPanicError())?.context?.operation).toBe('引擎崩溃');
+        expect(database.classifyError(new Error('plain'))).toBeNull();
+    });
+    it('operationLabels 可覆盖默认标签', () => {
+        const database = createPrismaDatabaseModule({
+            PrismaClient: Client,
+            PrismaNamespace: NAMESPACE,
+            operationLabels: { known: 'ClientKnown' },
+        });
+        expect(database.classifyError(new NAMESPACE.PrismaClientKnownRequestError())?.context?.operation).toBe('ClientKnown');
+    });
+    it('dispose 调用 db.$disconnect()', async () => {
+        const database = createPrismaDatabaseModule({ PrismaClient: Client, PrismaNamespace: NAMESPACE });
+        const client = await database.createClient({ config: TEST_CONFIG, postgresConfig: undefined });
+        await database.dispose?.(client);
+        expect(client.disconnected).toBe(true);
+    });
+});

package/output/app/default-modules.d.ts

@@ -0,0 +1,23 @@
+import type { ModuleName, ServerModule } from './module.js';
+/**
+ * 默认 `env` 模块（P1 空实现）。
+ *
+ * `loadEnvFiles()` 是独立导出、在骨架之前调用（决策 #5），因此这里只作为「封闭集合内的合法名字」存在。
+ */
+export declare function createEnvModule(): ServerModule;
+/**
+ * P1 默认 `redis` 模块（透传）。
+ *
+ * 骨架只持有 `createRedis()` 返回的 `{ client, dispose }`；未传 `createRedis` 时第 4 步空转
+ * （notice 即是此形态）。
+ */
+export declare function createRedisModule(): ServerModule;
+/**
+ * P1 有默认实现的模块（`env` / `redis`）。
+ *
+ * ⚠️ 故意不含 `database`：common 无法引用各仓生成的 Prisma client（决策 #8），给个「不建连」的
+ * 空实现会埋下静默无 DB 的雷，因此 `database` 必须由调用方**显式**给出
+ * `createPrismaDatabaseModule({ ... })` 或 `false`（装配期强制，见 `assemble.ts`）。
+ */
+export declare function createDefaultModules(): Partial<Record<ModuleName, ServerModule>>;
+//# sourceMappingURL=default-modules.d.ts.map

package/output/app/default-modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-modules.d.ts","sourceRoot":"","sources":["../../source/app/default-modules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE3D;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,YAAY,CAYhD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAKhF"}

package/output/app/default-modules.js

@@ -0,0 +1,40 @@
+/**
+ * 默认 `env` 模块（P1 空实现）。
+ *
+ * `loadEnvFiles()` 是独立导出、在骨架之前调用（决策 #5），因此这里只作为「封闭集合内的合法名字」存在。
+ */
+export function createEnvModule() {
+    return { name: 'env' };
+}
+/**
+ * P1 默认 `redis` 模块（透传）。
+ *
+ * 骨架只持有 `createRedis()` 返回的 `{ client, dispose }`；未传 `createRedis` 时第 4 步空转
+ * （notice 即是此形态）。
+ */
+export function createRedisModule() {
+    return {
+        name: 'redis',
+        steps: {
+            createRedis: (ctx) => {
+                const handle = ctx.options.createRedis?.(ctx.options.config);
+                if (handle) {
+                    ctx.state.redis = handle;
+                }
+            },
+        },
+    };
+}
+/**
+ * P1 有默认实现的模块（`env` / `redis`）。
+ *
+ * ⚠️ 故意不含 `database`：common 无法引用各仓生成的 Prisma client（决策 #8），给个「不建连」的
+ * 空实现会埋下静默无 DB 的雷，因此 `database` 必须由调用方**显式**给出
+ * `createPrismaDatabaseModule({ ... })` 或 `false`（装配期强制，见 `assemble.ts`）。
+ */
+export function createDefaultModules() {
+    return {
+        env: createEnvModule(),
+        redis: createRedisModule(),
+    };
+}

package/output/app/define-server.d.ts

@@ -0,0 +1,12 @@
+import type { DefineServerOptions, ServerInstance } from './types.js';
+/**
+ * 模块化装配 + 15 步固定编排（design §3 / §4 / §5；提案 §11）。
+ *
+ * 返回**原生 `FastifyInstance`**（不包 `fastify-plugin`、不返回包装对象）——调用方可直接
+ * `app.swagger()` / `app.inject()` / `app.decorate()`。`mode: 'openapi-build'` 时不 listen，
+ * 由调用方读 `app.swagger()`。
+ *
+ * `Db` 由 `modules.database`（`database` 模块的 `createClient` 返回类型）推断（决策 10-2）。
+ */
+export declare function defineServer<Db = unknown, S = unknown>(options: DefineServerOptions<Db, S>): Promise<ServerInstance>;
+//# sourceMappingURL=define-server.d.ts.map

package/output/app/define-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-server.d.ts","sourceRoot":"","sources":["../../source/app/define-server.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,mBAAmB,EAInB,cAAc,EAIf,MAAM,YAAY,CAAA;AA4QnB;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAC1D,OAAO,EAAE,mBAAmB,CAAC,EAAE,EAAE,CAAC,CAAC,GAClC,OAAO,CAAC,cAAc,CAAC,CAsBzB"}

package/output/app/define-server.js

@@ -0,0 +1,289 @@
+import { Disposer } from '@taicode/common-base';
+import Fastify, {} from 'fastify';
+import { assembleModules } from './assemble.js';
+import { attachSignalHandlers } from './signal.js';
+import { SHUTDOWN_ORDER } from './shutdown.js';
+import { SKIP_BY_MODE, STEP_ORDER } from './steps.js';
+const NOOP_LOGGER = {
+    debug: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+function requireApp(state) {
+    if (!state.app) {
+        throw new Error('Fastify instance has not been created yet');
+    }
+    return state.app;
+}
+function resolveLog(options, state) {
+    if (options.log) {
+        return options.log;
+    }
+    if (state.app) {
+        return state.app.log;
+    }
+    return NOOP_LOGGER;
+}
+function collectHooks(resolved) {
+    const hooks = {};
+    for (const name of resolved.order) {
+        const module = resolved.byName[name];
+        if (module?.hooks) {
+            Object.assign(hooks, module.hooks);
+        }
+    }
+    return hooks;
+}
+function collectPlugins(resolved, options) {
+    const plugins = [];
+    for (const name of resolved.order) {
+        const module = resolved.byName[name];
+        if (module?.plugins) {
+            plugins.push(...module.plugins);
+        }
+    }
+    if (options.extraPlugins) {
+        plugins.push(...options.extraPlugins);
+    }
+    return plugins;
+}
+function buildStepImplementations(resolved, options, moduleHooks) {
+    const implementations = {};
+    // 1) 固定骨架步骤的内置实现（模块可覆盖既定槽位，但无法新增 / 重排步骤）
+    implementations.createFastify = (ctx) => {
+        ctx.state.app = Fastify({ logger: ctx.options.config.loadConfig().debug, trustProxy: true });
+    };
+    implementations.registerCorePlugins = async (ctx) => {
+        const app = requireApp(ctx.state);
+        for (const plugin of collectPlugins(resolved, ctx.options)) {
+            await app.register(plugin);
+        }
+    };
+    implementations.onClose = (ctx) => {
+        const shutdownImplementations = buildShutdownImplementations(resolved, moduleHooks);
+        requireApp(ctx.state).addHook('onClose', () => runShutdown(ctx, shutdownImplementations, moduleHooks));
+    };
+    implementations.ready = async (ctx) => {
+        await requireApp(ctx.state).ready();
+    };
+    implementations.listen = async (ctx) => {
+        const app = requireApp(ctx.state);
+        const host = ctx.options.serverOptions?.host ?? '0.0.0.0';
+        const port = ctx.options.serverOptions?.port ?? ctx.options.config.loadConfig().port;
+        await app.listen({ port, host });
+        if (ctx.options.signal !== false) {
+            attachSignalHandlers(app, ctx.log);
+        }
+    };
+    // 2) 数据层端口 → 第 3 步（database 模块的整体覆盖也在此生效）
+    const database = resolved.database;
+    if (database) {
+        implementations['database.createClient'] = async (ctx) => {
+            const loadPostgresConfig = ctx.options.config.loadPostgresConfig;
+            const postgresConfig = loadPostgresConfig ? await loadPostgresConfig() : undefined;
+            ctx.state.db = await database.createClient({ config: ctx.options.config, postgresConfig });
+        };
+    }
+    // 3) 模块贡献的步骤实现（注册顺序 = MODULE_NAMES 顺序）
+    for (const name of resolved.order) {
+        const module = resolved.byName[name];
+        if (module?.steps) {
+            Object.assign(implementations, module.steps);
+        }
+    }
+    // 4) 调用方槽位（调用方优先级最高）
+    if (options.setupCompilers) {
+        implementations.setupCompilers = (ctx) => {
+            ctx.options.setupCompilers?.(requireApp(ctx.state));
+        };
+    }
+    if (options.initGlobalConfig) {
+        implementations.initGlobalConfig = (ctx) => {
+            const globalConfigOptions = {
+                redisUrl: ctx.options.config.resolveRedisUrl?.(),
+                channelPrefix: ctx.options.config.resolveCachePrefix?.(),
+            };
+            const dispose = ctx.options.initGlobalConfig?.(ctx.state.db, globalConfigOptions);
+            if (typeof dispose === 'function') {
+                ctx.state.disposeConfig = dispose;
+            }
+        };
+    }
+    if (options.initClients) {
+        implementations.initClients = async (ctx) => {
+            const unsubscribe = await ctx.options.initClients?.({
+                db: ctx.state.db,
+                redis: ctx.state.redis?.client,
+                globalConfig: ctx.state.globalConfig,
+            });
+            if (typeof unsubscribe === 'function') {
+                ctx.state.unsubscribe = unsubscribe;
+            }
+        };
+    }
+    implementations.createServices = (ctx) => {
+        ctx.state.services = ctx.options.createServices({
+            db: ctx.state.db,
+            redis: ctx.state.redis?.client,
+            globalConfig: ctx.state.globalConfig,
+        });
+    };
+    if (options.initServices || options.afterInit) {
+        implementations.initServices = async (ctx) => {
+            if (ctx.options.initServices) {
+                await ctx.options.initServices({ services: ctx.state.services });
+            }
+            if (ctx.options.afterInit) {
+                const disposer = await ctx.options.afterInit({
+                    db: ctx.state.db,
+                    redis: ctx.state.redis?.client,
+                    globalConfig: ctx.state.globalConfig,
+                    services: ctx.state.services,
+                });
+                if (typeof disposer === 'function') {
+                    ctx.state.disposer.addDisposer(disposer);
+                }
+            }
+        };
+    }
+    if (options.backgroundWorkers) {
+        implementations.backgroundWorkers = async (ctx) => {
+            await ctx.options.backgroundWorkers?.({
+                db: ctx.state.db,
+                redis: ctx.state.redis?.client,
+                globalConfig: ctx.state.globalConfig,
+                services: ctx.state.services,
+                disposer: ctx.state.disposer,
+            });
+        };
+    }
+    implementations.registerRouters = async (ctx) => {
+        await ctx.options.registerRouters(requireApp(ctx.state), { services: ctx.state.services });
+    };
+    if (options.afterReady) {
+        implementations.afterReady = async (ctx) => {
+            await ctx.options.afterReady?.({ app: requireApp(ctx.state), services: ctx.state.services });
+        };
+    }
+    return implementations;
+}
+async function disposeServiceMap(services) {
+    if (typeof services !== 'object' || services === null) {
+        return;
+    }
+    const record = services;
+    const pending = Object.values(record).map((service) => {
+        const candidate = service;
+        return typeof candidate.dispose === 'function' ? candidate.dispose() : undefined;
+    });
+    await Promise.allSettled(pending);
+}
+function buildShutdownImplementations(resolved, moduleHooks) {
+    const implementations = {
+        stopProducers: async (ctx) => {
+            await ctx.state.disposer.dispose();
+        },
+        unsubscribeConfig: async (ctx) => {
+            await ctx.state.unsubscribe?.();
+        },
+        disposeConfig: async (ctx) => {
+            await ctx.state.disposeConfig?.();
+        },
+        disposeServices: async (ctx) => {
+            const disposeServices = ctx.options.disposeServices ?? moduleHooks.disposeServices;
+            if (disposeServices) {
+                await disposeServices({ services: ctx.state.services });
+            }
+            else {
+                await disposeServiceMap(ctx.state.services);
+            }
+        },
+        disposeClients: async (ctx) => {
+            const disposeClients = ctx.options.disposeClients ?? moduleHooks.disposeClients;
+            await disposeClients?.();
+        },
+        disposeRedis: async (ctx) => {
+            await ctx.state.redis?.dispose();
+        },
+        disposeDb: async (ctx) => {
+            await resolved.database?.dispose?.(ctx.state.db);
+        },
+    };
+    for (const name of resolved.order) {
+        const module = resolved.byName[name];
+        if (module?.shutdown) {
+            Object.assign(implementations, module.shutdown);
+        }
+    }
+    return implementations;
+}
+async function runShutdown(ctx, implementations, moduleHooks) {
+    const errors = [];
+    const options = ctx.options;
+    const shutdown = options.shutdown ?? moduleHooks.shutdown;
+    const beforeShutdown = options.beforeShutdown ?? moduleHooks.beforeShutdown;
+    if (shutdown) {
+        try {
+            await shutdown('onClose');
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    else {
+        if (beforeShutdown) {
+            try {
+                await beforeShutdown();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        for (const step of SHUTDOWN_ORDER) {
+            const implementation = implementations[step];
+            if (!implementation) {
+                continue;
+            }
+            try {
+                await implementation(ctx);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        ctx.log.error({ errors, count: errors.length }, '[shutdown] completed with errors');
+    }
+}
+/**
+ * 模块化装配 + 15 步固定编排（design §3 / §4 / §5；提案 §11）。
+ *
+ * 返回**原生 `FastifyInstance`**（不包 `fastify-plugin`、不返回包装对象）——调用方可直接
+ * `app.swagger()` / `app.inject()` / `app.decorate()`。`mode: 'openapi-build'` 时不 listen，
+ * 由调用方读 `app.swagger()`。
+ *
+ * `Db` 由 `modules.database`（`database` 模块的 `createClient` 返回类型）推断（决策 10-2）。
+ */
+export async function defineServer(options) {
+    const internal = options;
+    const mode = internal.mode ?? 'production';
+    const resolved = assembleModules(internal.modules);
+    const state = { disposer: new Disposer() };
+    const moduleHooks = collectHooks(resolved);
+    const implementations = buildStepImplementations(resolved, internal, moduleHooks);
+    const skipped = new Set(SKIP_BY_MODE[mode]);
+    for (const step of STEP_ORDER) {
+        if (skipped.has(step)) {
+            continue;
+        }
+        const ctx = { options: internal, state, log: resolveLog(internal, state) };
+        ctx.log.debug({ step }, '[boot]');
+        const implementation = implementations[step];
+        if (implementation) {
+            await implementation(ctx);
+        }
+    }
+    return requireApp(state);
+}

package/output/app/define-server.test.d.ts

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