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

package/output/app/env.test.js

@@ -1,78 +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';
-const ENV_KEYS = [
-    'LAYER',
-    'OVERRIDE',
-    'ONLY_DEV',
-    'ONLY_ENV',
-    'ONLY_LOCAL',
-    'EXTERNAL_ONLY',
-    'EXPORTED',
-    'QUOTED',
-    'MULTI',
-    'HASHED',
-];
-describe('loadEnvFiles', () => {
-    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);
-    });
-    afterEach(() => {
-        process.chdir(previousCwd);
-        rmSync(directory, { recursive: true, force: true });
-        for (const key of ENV_KEYS) {
-            delete process.env[key];
-        }
-        vi.resetModules();
-    });
-    it('优先级：外部注入 > .env.local > .env > .env.dev', async () => {
-        process.env.LAYER = 'external';
-        process.env.EXTERNAL_ONLY = 'external';
-        vi.resetModules();
-        const { loadEnvFiles } = await import('./env.js');
-        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\n');
-        vi.resetModules();
-        const { loadEnvFiles } = await import('./env.js');
-        loadEnvFiles(['.env.test.local']);
-        expect(process.env.OVERRIDE).toBe('test-local');
-    });
-    it('缺失文件不报错', async () => {
-        rmSync(join(directory, '.env.local'));
-        vi.resetModules();
-        const { loadEnvFiles } = await import('./env.js');
-        expect(() => loadEnvFiles()).not.toThrow();
-        expect(process.env.ONLY_DEV).toBe('dev');
-    });
-    it('dotenv 语义：export 前缀 / 引号 / 转义 / 多行 / 行尾注释（与四家现状逐字一致）', async () => {
-        writeFileSync(join(directory, '.env.local'), [
-            'export EXPORTED=1',
-            'QUOTED="a b"',
-            'MULTI="line1\\nline2"',
-            'HASHED=value # 行尾注释',
-        ].join('\n'));
-        vi.resetModules();
-        const { loadEnvFiles } = await import('./env.js');
-        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');
-    });
-});

package/output/app/module.d.ts

@@ -1,88 +0,0 @@
-import type { SystemError } from '@taicode/common-base';
-import type { FastifyPluginAsync } from 'fastify';
-import type { ConfigModule, ServerHooks, ShutdownImplementations, StepImplementations } from './types.js';
-/**
- * 封闭模块名集合（design §3.1 十项）。
- *
- * 数组顺序即「注册顺序」，也是装配期报错文案里 `Allowed: ...` 的顺序，**不得重排**。
- */
-export declare const MODULE_NAMES: readonly ["env", "database", "redis", "context", "response", "cors", "schema", "rate-limit", "auth", "openapi"];
-export type ModuleName = (typeof MODULE_NAMES)[number];
-/**
- * P1 尚未提供默认实现的模块 → 各自的落地阶段（design §3.1 十项里除 `env` / `database` / `redis`
- * 之外的七个）。阶段号取自 `proposals/P1-boot-shutdown.md`：`openapi` 在 P2、`auth` 在 P4、其余在 P3。
- *
- * P1 过渡规则（design §3.2 + 提案 §3.3）：这些名字**必须由调用方显式写 `false`**（或直接提供
- * 一个同名的整体覆盖实现），否则装配期按**真实阶段号**报错 —— 静默 no-op 会让调用方少注册插件
- * 却启动成功。
- */
-export declare const PENDING_MODULES: {
-    readonly context: "P3";
-    readonly response: "P3";
-    readonly cors: "P3";
-    readonly schema: "P3";
-    readonly 'rate-limit': "P3";
-    readonly auth: "P4";
-    readonly openapi: "P2";
-};
-export type PendingModuleName = keyof typeof PENDING_MODULES;
-export type PendingModuleStage = (typeof PENDING_MODULES)[PendingModuleName];
-/** 模块契约：可贡献「初始化步骤实现 / Fastify 插件 / 生命周期 hook / 关闭逻辑」四类东西（design §3.1） */
-export interface ServerModule {
-    /** 具名单元；装配期校验「键 == name」「不重复」「在封闭集合内」 */
-    name: ModuleName;
-    /** ① 初始化步骤实现：key 只能是 §4.1 的既定槽位，不得新增 / 重排步骤 */
-    steps?: Partial<StepImplementations>;
-    /** ② Fastify 插件：注册进第 7 步 `registerCorePlugins` */
-    plugins?: FastifyPluginAsync[];
-    /** ③ 生命周期 hook（见 design §4.2）；模块提供的 hook 不再是顶层选项 */
-    hooks?: ServerHooks;
-    /** ④ 关闭逻辑：只能命中 §5 的 7 个既定槽位 */
-    shutdown?: Partial<ShutdownImplementations>;
-    /** 依赖的其它模块名；装配期做拓扑校验（指向被跳过的模块即报错） */
-    dependsOn?: ModuleName[];
-}
-/** 模块装配入参（design §3.2）：未出现 = 默认实现；`false` = 跳过；对象 = 整体覆盖 */
-export interface ModuleAssembly<Db = unknown> {
-    env?: false | ServerModule;
-    database?: false | DatabaseModule<Db>;
-    redis?: false | ServerModule;
-    context?: false | ServerModule;
-    response?: false | ServerModule;
-    cors?: false | ServerModule;
-    schema?: false | ServerModule;
-    'rate-limit'?: false | ServerModule;
-    auth?: false | ServerModule;
-    openapi?: false | ServerModule;
-}
-/** `database` 模块步骤 3 的入参（design §3.3） */
-export interface DatabaseClientParams {
-    config: ConfigModule;
-    postgresConfig: unknown;
-}
-/** 各仓生成的 Prisma 命名空间里、错误分类用到的 5 个错误类构造器（跨包 instanceof 不可靠，决策 #9） */
-export interface PrismaErrorConstructors {
-    PrismaClientKnownRequestError: new (...args: never[]) => unknown;
-    PrismaClientUnknownRequestError: new (...args: never[]) => unknown;
-    PrismaClientValidationError: new (...args: never[]) => unknown;
-    PrismaClientInitializationError: new (...args: never[]) => unknown;
-    PrismaClientRustPanicError: new (...args: never[]) => unknown;
-}
-export type PrismaOperationKey = 'known' | 'unknown' | 'validation' | 'initialization' | 'rustPanic';
-/** 可选覆盖的 operation 标签（默认对齐 design §2.3 的统一口径） */
-export type PrismaOperationLabels = Partial<Record<PrismaOperationKey, string>>;
-/**
- * 数据层端口（design §3.3）：任何实现只要满足它即可整体替换。
- *
- * 契约相同（同名、同贡献面）即可换实现——「支持非 Prisma 数据库」靠模块替换达成。
- */
-export interface DatabaseModule<Db = unknown> extends ServerModule {
-    name: 'database';
-    /** 步骤 3：建立连接。默认 Prisma 实现 = `new PrismaClient(...)` */
-    createClient(params: DatabaseClientParams): Db | Promise<Db>;
-    /** 错误分类：命中 → `SystemError('DATABASE_ERROR', …)`；未命中 → `null`（落回 UNKNOWN_ERROR 兜底） */
-    classifyError(error: unknown): SystemError | null;
-    /** §5-7：释放连接。默认 = `db.$disconnect()` */
-    dispose?(db: Db): Promise<void>;
-}
-//# sourceMappingURL=module.d.ts.map

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

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

package/output/app/module.js

@@ -1,34 +0,0 @@
-/**
- * 封闭模块名集合（design §3.1 十项）。
- *
- * 数组顺序即「注册顺序」，也是装配期报错文案里 `Allowed: ...` 的顺序，**不得重排**。
- */
-export const MODULE_NAMES = [
-    'env',
-    'database',
-    'redis',
-    'context',
-    'response',
-    'cors',
-    'schema',
-    'rate-limit',
-    'auth',
-    'openapi',
-];
-/**
- * P1 尚未提供默认实现的模块 → 各自的落地阶段（design §3.1 十项里除 `env` / `database` / `redis`
- * 之外的七个）。阶段号取自 `proposals/P1-boot-shutdown.md`：`openapi` 在 P2、`auth` 在 P4、其余在 P3。
- *
- * P1 过渡规则（design §3.2 + 提案 §3.3）：这些名字**必须由调用方显式写 `false`**（或直接提供
- * 一个同名的整体覆盖实现），否则装配期按**真实阶段号**报错 —— 静默 no-op 会让调用方少注册插件
- * 却启动成功。
- */
-export const PENDING_MODULES = {
-    context: 'P3',
-    response: 'P3',
-    cors: 'P3',
-    schema: 'P3',
-    'rate-limit': 'P3',
-    auth: 'P4',
-    openapi: 'P2',
-};

package/output/app/shutdown.d.ts

@@ -1,9 +0,0 @@
-/**
- * 固定关闭 7 步（design §5）——**顺序写死在数组里**。
- *
- * 关键修正（相对现状）：Redis 晚于 queue/cache 消费者释放；afterInit（如 LDAP）资源进第 1 步。
- * 单步抛错记录后**继续**后续步骤，最后聚合上报（避免「config 报错导致 DB 没关」）。
- */
-export declare const SHUTDOWN_ORDER: readonly ["stopProducers", "unsubscribeConfig", "disposeConfig", "disposeServices", "disposeClients", "disposeRedis", "disposeDb"];
-export type ShutdownStepName = (typeof SHUTDOWN_ORDER)[number];
-//# sourceMappingURL=shutdown.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../source/app/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,cAAc,oIAQjB,CAAA;AAEV,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA"}

package/output/app/shutdown.js

@@ -1,15 +0,0 @@
-/**
- * 固定关闭 7 步（design §5）——**顺序写死在数组里**。
- *
- * 关键修正（相对现状）：Redis 晚于 queue/cache 消费者释放；afterInit（如 LDAP）资源进第 1 步。
- * 单步抛错记录后**继续**后续步骤，最后聚合上报（避免「config 报错导致 DB 没关」）。
- */
-export const SHUTDOWN_ORDER = [
-    'stopProducers',
-    'unsubscribeConfig',
-    'disposeConfig',
-    'disposeServices',
-    'disposeClients',
-    'disposeRedis',
-    'disposeDb',
-];

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

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

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

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

package/output/app/shutdown.test.js

@@ -1,149 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { defineServer } from './define-server.js';
-import { SHUTDOWN_ORDER } from './shutdown.js';
-const P1_OPT_OUT = {
-    context: false,
-    response: false,
-    cors: false,
-    schema: false,
-    'rate-limit': false,
-    auth: false,
-    openapi: false,
-    database: false,
-};
-const DUMMY_ERRORS = {
-    UserError: class extends Error {
-    },
-    SystemError: class extends Error {
-    },
-};
-function createTestLog() {
-    const errors = [];
-    const log = {
-        debug: () => undefined,
-        info: () => undefined,
-        warn: () => undefined,
-        error: (obj) => {
-            errors.push(obj);
-        },
-    };
-    return { log, errors };
-}
-function createBaseOptions(overrides = {}) {
-    return {
-        serviceName: 'test',
-        title: 'Test',
-        description: 'Test service',
-        errors: DUMMY_ERRORS,
-        config: { loadConfig: () => ({ debug: false, port: 0 }) },
-        modules: { ...P1_OPT_OUT },
-        serverOptions: { port: 0, host: '127.0.0.1' },
-        signal: false,
-        createServices: () => ({}),
-        registerRouters: () => undefined,
-        ...overrides,
-    };
-}
-function createRecordingShutdownModule(record, throwOn) {
-    const createStep = (name) => () => {
-        record.push(name);
-        if (name === throwOn) {
-            throw new Error(`boom:${name}`);
-        }
-    };
-    const shutdown = {
-        stopProducers: createStep('stopProducers'),
-        unsubscribeConfig: createStep('unsubscribeConfig'),
-        disposeConfig: createStep('disposeConfig'),
-        disposeServices: createStep('disposeServices'),
-        disposeClients: createStep('disposeClients'),
-        disposeRedis: createStep('disposeRedis'),
-        disposeDb: createStep('disposeDb'),
-    };
-    return { name: 'env', shutdown };
-}
-describe('关闭 7 步', () => {
-    it('顺序写死、beforeShutdown 在最前', async () => {
-        const record = [];
-        const app = await defineServer(createBaseOptions({
-            modules: { ...P1_OPT_OUT, env: createRecordingShutdownModule(record) },
-            beforeShutdown: () => {
-                record.push('beforeShutdown');
-            },
-        }));
-        await app.close();
-        expect(record).toEqual(['beforeShutdown', ...SHUTDOWN_ORDER]);
-    });
-    it('单步抛错不阻断后续，且聚合上报（不吞第一个错误）', async () => {
-        const record = [];
-        const { log, errors } = createTestLog();
-        const app = await defineServer(createBaseOptions({
-            log,
-            modules: { ...P1_OPT_OUT, env: createRecordingShutdownModule(record, 'disposeConfig') },
-            beforeShutdown: () => {
-                record.push('beforeShutdown');
-                throw new Error('boom:beforeShutdown');
-            },
-        }));
-        await app.close();
-        // disposeConfig 抛错后，4~7 步仍然执行
-        expect(record).toEqual(['beforeShutdown', ...SHUTDOWN_ORDER]);
-        expect(errors).toHaveLength(1);
-        const aggregated = errors[0];
-        expect(aggregated.count).toBe(2);
-        expect(aggregated.errors).toHaveLength(2);
-    });
-    it('shutdown 选项整体覆盖默认关闭流程', async () => {
-        const record = [];
-        const app = await defineServer(createBaseOptions({
-            modules: { ...P1_OPT_OUT, env: createRecordingShutdownModule(record) },
-            beforeShutdown: () => {
-                record.push('beforeShutdown');
-            },
-            shutdown: () => {
-                record.push('custom');
-            },
-        }));
-        await app.close();
-        expect(record).toEqual(['custom']);
-    });
-    it('模块 hooks.beforeShutdown 生效（调用方选项优先）', async () => {
-        const record = [];
-        const module = {
-            name: 'env',
-            hooks: {
-                beforeShutdown: () => {
-                    record.push('module-before');
-                },
-            },
-            shutdown: {
-                stopProducers: () => {
-                    record.push('stopProducers');
-                },
-            },
-        };
-        const app = await defineServer(createBaseOptions({ modules: { ...P1_OPT_OUT, env: module } }));
-        await app.close();
-        expect(record).toEqual(['module-before', 'stopProducers']);
-    });
-    it('默认 disposeServices 用 Promise.allSettled 释放 services（单服务抛错不影响其它）', async () => {
-        let disposed = 0;
-        const app = await defineServer(createBaseOptions({
-            createServices: () => ({
-                a: {
-                    dispose: () => {
-                        disposed += 1;
-                    },
-                },
-                b: {
-                    dispose: () => {
-                        disposed += 1;
-                        throw new Error('service dispose failed');
-                    },
-                },
-            }),
-        }));
-        await app.close();
-        expect(disposed).toBe(2);
-    });
-});

package/output/app/signal.d.ts

@@ -1,12 +0,0 @@
-import type { FastifyInstance } from 'fastify';
-import type { LoggerLike } from './types.js';
-/**
- * 内置信号处理（design §4.1 第 15 步尾部）。
- *
- * `SIGTERM` / `SIGINT` / `uncaughtException` / `unhandledRejection` ⇒ `app.close()`（触发 onClose
- * 的关闭 7 步）⇒ `process.exit(0/1)`。可通过 `signal: false` 整体关掉（测试 / 嵌入场景）。
- *
- * @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,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,IAAI,CA2CtF"}

package/output/app/steps.d.ts

@@ -1,17 +0,0 @@
-import type { ServerMode } from './types.js';
-/**
- * 固定 15 步（design §4.1）——**顺序写死在数组里**。
- *
- * 模块只能往这些「既定槽位」里填实现，不得新增步骤、不得重排、不得改变 §4.1 的依赖偏序。
- */
-export declare const STEP_ORDER: readonly ["createFastify", "setupCompilers", "database.createClient", "createRedis", "initGlobalConfig", "initClients", "registerCorePlugins", "createServices", "initServices", "backgroundWorkers", "registerRouters", "onClose", "ready", "afterReady", "listen"];
-export type StepName = (typeof STEP_ORDER)[number];
-/**
- * 各模式跳过的步骤（design §4.1 / §4.3）。
- *
- * - `test`：关后台 worker 与 ready 后动作（第 10 / 14 步）。
- * - `openapi-build`：跳过 [5,6,9,10,14,15] 与一切连库/连 Redis 的动作，但仍保留 [3,4]（10-3：
- *   P1 沿用四家现状「不跳过第 3/4 步」，跳过错步留 P2），并保留 [7,8,11] 以保证 `app.swagger()` 完整。
- */
-export declare const SKIP_BY_MODE: Record<ServerMode, readonly StepName[]>;
-//# sourceMappingURL=steps.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../../source/app/steps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;;GAIG;AACH,eAAO,MAAM,UAAU,sQAgBb,CAAA;AAEV,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,QAAQ,EAAE,CAWhE,CAAA"}

package/output/app/steps.js

@@ -1,41 +0,0 @@
-/**
- * 固定 15 步（design §4.1）——**顺序写死在数组里**。
- *
- * 模块只能往这些「既定槽位」里填实现，不得新增步骤、不得重排、不得改变 §4.1 的依赖偏序。
- */
-export const STEP_ORDER = [
-    'createFastify',
-    'setupCompilers',
-    'database.createClient',
-    'createRedis',
-    'initGlobalConfig',
-    'initClients',
-    'registerCorePlugins',
-    'createServices',
-    'initServices',
-    'backgroundWorkers',
-    'registerRouters',
-    'onClose',
-    'ready',
-    'afterReady',
-    'listen',
-];
-/**
- * 各模式跳过的步骤（design §4.1 / §4.3）。
- *
- * - `test`：关后台 worker 与 ready 后动作（第 10 / 14 步）。
- * - `openapi-build`：跳过 [5,6,9,10,14,15] 与一切连库/连 Redis 的动作，但仍保留 [3,4]（10-3：
- *   P1 沿用四家现状「不跳过第 3/4 步」，跳过错步留 P2），并保留 [7,8,11] 以保证 `app.swagger()` 完整。
- */
-export const SKIP_BY_MODE = {
-    production: [],
-    test: ['backgroundWorkers', 'afterReady'],
-    'openapi-build': [
-        'initGlobalConfig',
-        'initClients',
-        'initServices',
-        'backgroundWorkers',
-        'afterReady',
-        'listen',
-    ],
-};

package/output/app/types.d.ts

@@ -1,149 +0,0 @@
-import type { Disposer } from '@taicode/common-base';
-import type { FastifyInstance, FastifyPluginAsync } from 'fastify';
-import type { ModuleAssembly } from './module.js';
-import type { ShutdownStepName } from './shutdown.js';
-import type { StepName } from './steps.js';
-/** 原生 Fastify 实例，原样返回（不包 `fastify-plugin`、不返回包装对象） */
-export type ServerInstance = FastifyInstance;
-export type ServerMode = 'production' | 'test' | 'openapi-build';
-/** 错误工厂：由各服务 `errors.ts` 的 `define()` 产出（`class extends Error`） */
-export type ErrorFactory = new (...args: never[]) => Error;
-export interface ErrorFactories {
-    UserError: ErrorFactory;
-    SystemError: ErrorFactory;
-}
-/** 运行时配置快照（对应各仓导出的 `config` 常量） */
-export interface RuntimeConfig {
-    debug: boolean;
-    port: number;
-}
-/**
- * 配置模块端口（design §4.2）。`loadConfig` 必填；依赖数据层的服务才需要 `loadPostgresConfig`。
- *
- * 骨架不替调用方加载 env —— 请先自行调用 `loadEnvFiles()`（详见 `./env.js`）。
- */
-export interface ConfigModule {
-    loadConfig: () => RuntimeConfig;
-    loadPostgresConfig?: () => unknown | Promise<unknown>;
-    resolveRedisUrl?: () => string | undefined;
-    resolveCachePrefix?: () => string | undefined;
-}
-/** 骨架只按 `(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;
-}
-/**
- * 骨架**不操作** Redis 命令，只持有并在关闭时透传 dispose；
- * 因此保持开放类型，各仓注入自己的客户端（如 node-redis）不受约束。
- */
-export type RedisLike = unknown;
-export interface RedisHandle {
-    client: RedisLike;
-    dispose: () => Promise<void>;
-}
-export type DisposeFunction = () => unknown;
-export type UnsubscribeFunction = () => unknown;
-export interface GlobalConfigOptions {
-    redisUrl?: string;
-    channelPrefix?: string;
-}
-/** 贯穿步骤 5/6/8 的依赖上下文 */
-export interface DbContext<Db = unknown> {
-    db: Db;
-    redis?: RedisLike;
-    globalConfig: unknown;
-}
-export interface ServicesContext<S = unknown> {
-    services: S;
-}
-export interface InitContext<Db = unknown, S = unknown> extends DbContext<Db> {
-    services: S;
-}
-export interface WorkersContext<Db = unknown, S = unknown> extends DbContext<Db> {
-    services: S;
-    disposer: Disposer;
-}
-export interface ReadyContext<S = unknown> {
-    app: FastifyInstance;
-    services: S;
-}
-export interface ServerOptions {
-    port: number;
-    host?: string;
-}
-export type ResolveMessage = (type: string, context: unknown, explicit?: string) => string | undefined;
-export type MapStatus = (type: string) => number | null;
-/** 骨架内部持有的运行时句柄（配置 / 关闭流程用） */
-export interface RuntimeState {
-    app?: FastifyInstance;
-    db?: unknown;
-    redis?: RedisHandle;
-    globalConfig?: unknown;
-    services?: unknown;
-    disposer: Disposer;
-    unsubscribe?: UnsubscribeFunction;
-    disposeConfig?: DisposeFunction;
-}
-/** 每个步骤执行时拿到的上下文（`log` 在 `createFastify` 之后默认降级/升级为 `app.log`） */
-export interface StepContext {
-    options: DefineServerOptions;
-    state: RuntimeState;
-    log: LoggerLike;
-}
-export type StepRunner = (ctx: StepContext) => unknown | Promise<unknown>;
-export type StepImplementations = Record<StepName, StepRunner>;
-export type ShutdownRunner = (ctx: StepContext) => unknown | Promise<unknown>;
-export type ShutdownImplementations = Record<ShutdownStepName, ShutdownRunner>;
-/** 模块可贡献的生命周期 hook（design §4.2） */
-export interface ServerHooks {
-    beforeShutdown?: () => unknown | Promise<unknown>;
-    shutdown?: (signal: string) => unknown | Promise<unknown>;
-    disposeServices?: (ctx: ServicesContext) => unknown | Promise<unknown>;
-    disposeClients?: () => unknown | Promise<unknown>;
-}
-/**
- * `defineServer()` 入参（design §3.4）。
- *
- * `Db` 由 `modules.database`（`database` 模块的 `createClient` 返回类型）**推断**（决策 10-2），
- * 因此调用方**不需要**在 `createServices` 里写 `as PrismaClient` 强转。
- */
-export interface DefineServerOptions<Db = unknown, S = unknown> {
-    serviceName: string;
-    title: string;
-    description: string;
-    version?: string;
-    mode?: ServerMode;
-    serverOptions?: ServerOptions;
-    serverUrl?: string | (() => string | null);
-    openapiVersion?: string;
-    docPath?: string;
-    log?: LoggerLike;
-    signal?: boolean;
-    errors: ErrorFactories;
-    messages?: Record<string, string>;
-    resolveMessage?: ResolveMessage;
-    mapStatus?: MapStatus;
-    modules?: ModuleAssembly<Db>;
-    config: ConfigModule;
-    setupCompilers?: (app: FastifyInstance) => void;
-    createRedis?: (config: ConfigModule) => RedisHandle | undefined;
-    initGlobalConfig?: (db: Db, opts: GlobalConfigOptions) => void | DisposeFunction;
-    onGlobalConfigChange?: (globalConfig: unknown) => void;
-    initClients?: (ctx: DbContext<Db>) => Promise<void | UnsubscribeFunction>;
-    extraPlugins?: FastifyPluginAsync[];
-    createServices: (ctx: DbContext<Db>) => S;
-    initServices?: (ctx: ServicesContext<S>) => Promise<void>;
-    backgroundWorkers?: (ctx: WorkersContext<Db, S>) => Promise<void>;
-    registerRouters: (app: FastifyInstance, ctx: ServicesContext<S>) => Promise<void> | void;
-    afterInit?: (ctx: InitContext<Db, S>) => Promise<DisposeFunction | void>;
-    afterReady?: (ctx: ReadyContext<S>) => Promise<void>;
-    beforeShutdown?: () => Promise<void> | void;
-    disposeServices?: (ctx: ServicesContext<S>) => Promise<void> | void;
-    disposeClients?: () => Promise<void> | void;
-    /** 覆盖默认关闭流程（design §3.4 / §5） */
-    shutdown?: (signal: string) => Promise<void> | void;
-}
-//# 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"}