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

package/output/auth/index.js

@@ -0,0 +1,196 @@
+import { catchIt, SystemError, UserError } from '@taicode/common-base';
+import { readConfigKey } from '../core/boot/context.js';
+import { readServerIdentity } from '../core/modules/identity/index.js';
+import { extractPermissionOperations } from '../core/modules/permission-operations/index.js';
+/** cookie 名缺省值（既未显式传入、配置也没给时使用） */
+const DEFAULT_COOKIE_NAMES = ['token'];
+/**
+ * 解析 cookie 名：显式参数 → 配置 `server.cookieNames` → 缺省值。
+ *
+ * **必须请求期调用**：出 spec 路径不跑 `config` 槽位，`ctx.config` 读到即抛 `CONFIG_UNAVAILABLE`。
+ */
+function resolveCookieNames(config, declared) {
+    if (declared !== undefined && declared.length > 0) {
+        return declared;
+    }
+    const server = readConfigKey(config, 'server');
+    return Array.isArray(server?.cookieNames) && server.cookieNames.length > 0 ? server.cookieNames : DEFAULT_COOKIE_NAMES;
+}
+function extractAuth(request, cookieNames) {
+    const authorization = request.headers.authorization;
+    if (typeof authorization === 'string' && authorization.startsWith('Bearer ')) {
+        return { token: authorization.slice('Bearer '.length).trim() };
+    }
+    if (typeof authorization === 'string' && authorization.startsWith('apikey-')) {
+        return { apiKey: authorization.slice('apikey-'.length).trim() };
+    }
+    for (const name of cookieNames) {
+        const value = request.cookies?.[name];
+        if (typeof value === 'string' && value) {
+            return { token: value };
+        }
+    }
+    return {};
+}
+/**
+ * 固定跳过判定（**不可覆盖**）：`OPTIONS` → 未匹配路由。
+ *
+ * 不按路径前缀特判文档出口：`GET /system/openapi` 自己声明了 `NoLoginRequired`，
+ * **路由是唯一事实来源**——这样「哪些接口免登录」永远能从路由声明上读出来。
+ *
+ * ## `NoLoginRequired` 为什么**不在这里**跳过
+ *
+ * 免登录 ≠ 不解析身份。二者混为一谈会有两类真实故障（account 上都发生过）：
+ *
+ * - `POST /permission/user/operation/list`（免登录 + `Request-user` 为空就返回空清单）
+ *   永远返回空清单，前端拿到的权限快照恒为空；
+ * - `POST /sign-out`（免登录 + `request.token` 存在才删除 SignIn Secret）永远删不掉密钥，
+ *   登出后 token 仍然有效。
+ *
+ * 所以免登录路由的处理放到 `preValidation` 里：**有凭证就尝试解析并回填身份，解析失败
+ * 一律当匿名放行**（公开接口不该因为一个过期 cookie 变成 400）。没有凭证时直接返回，
+ * 探针 / 文档抓取这类无 cookie 的高频请求不会多出一次校验调用。
+ */
+function shouldSkip(request) {
+    if (request.method === 'OPTIONS') {
+        return true;
+    }
+    return !request.routeOptions?.url;
+}
+/**
+ * 固定错误归类（**不可覆盖**）：`UserError` / `SystemError` 原样透出，其余 → `EXTERNAL_SERVICE_ERROR`。
+ *
+ * 提供方若想表达「凭证无效 / 权限不足」，必须自己抛标准错误——这正是「按标准设计实现」的落点。
+ */
+function toStandardAuthError(error) {
+    if (UserError.is(error) || SystemError.is(error)) {
+        return error;
+    }
+    return new SystemError('EXTERNAL_SERVICE_ERROR', { cause: error });
+}
+/**
+ * 从 OpenAPI 文档收集权限目录（**去重 + 稳定排序**）。
+ *
+ * 唯一来源就是 `app.swagger()`：不再同时维护一份 `onRoute` 注册表。两套来源必然漂移
+ * （`HEAD` / 前缀 / 插件路由只要有一处处理不同就对不上），而文档既能保证与对外契约一致，
+ * 也让「文档里有什么、权限系统里就有什么」成为可验证的事实。
+ *
+ * 同一 `operationId` 出现两次是路由声明问题（core 的 schema 守卫只保证字段存在，不保证唯一），
+ * 按首次出现保留并告警。稳定排序让目录内容不随注册顺序抖动，方便提供方 diff 与缓存。
+ */
+function collectPermissionOperations(app, log) {
+    const swagger = app.swagger;
+    if (typeof swagger !== 'function') {
+        log.warn('[PermissionOperation][auth] 未启用 OpenAPI 文档，跳过权限目录自注册');
+        return [];
+    }
+    const collected = extractPermissionOperations(swagger.call(app));
+    const seen = new Set();
+    const operations = [];
+    const duplicates = [];
+    for (const operation of collected) {
+        if (seen.has(operation.operation)) {
+            duplicates.push(operation.operation);
+            continue;
+        }
+        seen.add(operation.operation);
+        operations.push(operation);
+    }
+    if (duplicates.length > 0) {
+        log.warn({ operations: duplicates }, '[PermissionOperation][auth] 检测到重复 operationId，已按首次声明去重（请修正路由声明）');
+    }
+    operations.sort((a, b) => (a.operation < b.operation ? -1 : a.operation > b.operation ? 1 : 0));
+    return operations;
+}
+/** 提交权限目录（失败**不致命**：只记日志，不中断启动） */
+async function submitPermissionOperations(client, log, identity, operations) {
+    const { service, version } = identity;
+    if (!version) {
+        log.warn({ service }, '[PermissionOperation][auth] 身份块 version 为空：权限目录将无法按版本归组');
+    }
+    if (operations.length === 0) {
+        log.warn({ service, version }, '[PermissionOperation][auth] 未采集到任何带 operationId 的路由，跳过权限目录自注册（请检查路由 schema）');
+        return;
+    }
+    const result = await catchIt(client.registerPermissionOperations({ service, version, operations }));
+    if (result.isError()) {
+        log.error({ error: result.error, service, version, count: operations.length }, '[PermissionOperation][auth] 权限目录自注册失败（不阻断启动）');
+        return;
+    }
+    log.info({ service, version, count: operations.length }, '[PermissionOperation][auth] 权限目录自注册完成');
+}
+/**
+ * 构造标准 `auth` 中间件（具名单元 `name: 'auth'`）。
+ *
+ * `client` **必填**（类型上）且必须有运行期实现：装了鉴权却没有校验实现是配置错误，
+ * 构造期直接抛错——不留「请求期才 fail-closed」的窗口，也不允许静默放行。
+ */
+export function createAuthMiddleware(ctx, options) {
+    const client = options?.client;
+    if (!client || typeof client.verify !== 'function') {
+        throw new Error('[auth] auth 中间件缺少校验实现：请通过 `createAuthMiddleware(ctx, { client })` 注入鉴权提供方');
+    }
+    const register = (app) => {
+        const identity = readServerIdentity(app);
+        if (!identity) {
+            throw new Error('[auth] 读不到身份块：`createAuthMiddleware` 必须挂在 `startServer` / `generateOpenApi` 的 app 上');
+        }
+        app.addHook('preValidation', async (request) => {
+            if (shouldSkip(request)) {
+                return;
+            }
+            const optionalLogin = request.routeOptions.config?.accessControls?.includes('NoLoginRequired') === true;
+            // cookie 名**请求期**解析：显式参数优先，其次现读配置（配置可被运维改动）
+            const { token, apiKey } = extractAuth(request, resolveCookieNames(ctx.config, options.cookieNames));
+            if (!token && !apiKey) {
+                // 免登录路由：没有凭证就直接匿名，不必白跑一次校验（探针 / 文档抓取都属于这一类）
+                if (optionalLogin) {
+                    return;
+                }
+                throw new UserError('INVALID_TOKEN', undefined, '缺少访问凭证');
+            }
+            const verifyInput = {
+                token,
+                apiKey,
+                service: identity.service,
+                // 权限目录同源、与 url 解耦：优先路由 `schema.operationId`，未声明时回落 url
+                operation: request.routeOptions?.schema?.operationId ?? request.routeOptions?.url,
+                resource: request.params,
+                accessControls: request.routeOptions?.config?.accessControls,
+                metadata: {
+                    requestId: request.id,
+                    method: request.method,
+                    url: request.url,
+                    ip: request.ip,
+                    ips: request.ips,
+                    userAgent: request.headers['user-agent'],
+                    referrer: request.headers.referer,
+                },
+            };
+            try {
+                const result = await client.verify(verifyInput);
+                request.user = result.user;
+                request.token = result.token ?? token;
+            }
+            catch (error) {
+                // 免登录路由：凭证坏了也只是「没有身份」，不能因为一个过期 cookie 把公开接口变成 400
+                if (optionalLogin) {
+                    return;
+                }
+                throw toStandardAuthError(error);
+            }
+        });
+        // 权限目录自注册：**运行期无条件执行**（唯一前提是有 client，而 client 是必填的）。
+        //
+        // 时点必须在 `onReady`：`app.swagger()` 只有在 `ready()` 之后才可用（swagger 自身也挂
+        // `onReady`，且它在 core 阶段先注册，故本钩子执行时文档已就绪）。
+        //
+        // **为什么不需要区分入口**：`generateOpenApi` 根本不注册中间件（它只装路由与 schema
+        // 契约），所以本单元在出文档路径里压根不会被构造，不存在「构建期误写权限系统」的可能。
+        // 这也是「出文档不装配运行期能力」的直接收益：副作用随能力一起消失，不需要额外标记。
+        app.addHook('onReady', async () => {
+            await submitPermissionOperations(client, ctx.log, identity, collectPermissionOperations(app, ctx.log));
+        });
+    };
+    return { name: 'auth', register };
+}

package/output/core/assemble.d.ts

@@ -0,0 +1,64 @@
+import type { ErrorClassifier } from './modules/response/index.js';
+import type { ConfigEnv } from './env.js';
+import type { AppIdentity } from './types.js';
+import type { FastifyInstance } from 'fastify';
+/**
+ * core 步骤 `createFastify`（`prepare`）。
+ *
+ * **总是**建 pino logger（level = `LOG_LEVEL`，默认 `info`） + 内置 `requestId`（入站 `x-request-id`
+ * 复用 / `randomUUID`，日志字段 `requestId`）。`trustProxy: true` 与四家现状一致。
+ *
+ * 固定装配，**不从包对外导出**：对外入口只有 `defineServer` / `startServer` / `generateOpenApi`。
+ */
+export declare function createFastify(env: ConfigEnv): FastifyInstance;
+/**
+ * 出文档用的**最小实例**（`generateOpenApi` 专用）。
+ *
+ * 没有 logger、没有 `requestId`、没有 `trustProxy`——这些只在**有请求**时才有意义，
+ * 而构建期一条请求都不会发。`logger: false` 下 `app.log` 仍是 `abstract-logging` 的
+ * 空实现，满足 `LoggerLike`，因此下游单元拿到的 `ctx.log` 调用不会炸，也不会产生输出。
+ */
+export declare function createDocumentFastify(): FastifyInstance;
+/** core 装配入参 */
+export interface CoreRegistrationOptions {
+    /** 身份块（`service` / `title` / `version`）：openapi + 内置单元从这里读 */
+    identity: AppIdentity;
+    env: ConfigEnv;
+    /** 资源错误分类（各资源经 `ctx.registerClassifyError` 注册；缺省 = 落 `UNKNOWN_ERROR`） */
+    classifyResourceError?: ErrorClassifier;
+    /** 取**已加载**配置中某个键的访问器（cookie domain 等**惰性**取值；不得在构造期调用） */
+    readConfig: (key: string) => unknown;
+}
+/**
+ * **schema 契约**（固定序，不可替换）：`identity` → `schema`（zod compiler）→ 路由契约守卫。
+ *
+ * 两个入口都必须有它：
+ * - `startServer` 要让 zod 真的校验/序列化请求，并让「路由缺 `schema`」在注册处就失败；
+ * - `generateOpenApi` 要把 zod 转成 JSON Schema 出文档，也要同一个守卫——**文档就是权限目录**，
+ *   构建期放过的路由会在线上变成「接口永远判不过」。
+ *
+ * 单独成函数是为了让「运行期 core」与「文档 core」两条装配路径共用同一段契约，
+ * 而不用把整段运行期能力拖进出文档路径。
+ */
+export declare function registerSchemaContract(app: FastifyInstance, options: Pick<CoreRegistrationOptions, 'identity'>): void;
+/**
+ * **文档 core**（`generateOpenApi` 专用）：schema 契约 + swagger。
+ *
+ * 只有这三件事与「把 zod schema 转成 OpenAPI 文档」有关：身份（`info.title` /
+ * `info.version`）、zod compiler（转换前得能读懂 zod）、守卫（不让文档缺条目）、swagger（转换器）。
+ * `requestContext` / `cookie` / `response` / `requestId` 全部**不装**——它们只影响
+ * 请求怎么被处理，而构建期一条请求都不会发。
+ */
+export declare function registerDocumentCore(app: FastifyInstance, options: Pick<CoreRegistrationOptions, 'identity'>): Promise<void>;
+/**
+ * core 装配（固定序，不可替换）：`identity` → `schema`（+ 路由契约守卫）→ `requestContext`
+ * → `cookie` → `response` → `openapi` → `requestId` 回吐。
+ *
+ * 全部为框架内置能力，**不暴露选项面**；`request.ctx` 的装配也在这一步完成（`type-augment` 的
+ * 类型承诺因此总有运行期对应物）。**构造期不读配置**（`cookie` 的 domain 在请求期惰性读取），
+ * 故出 spec 路径（`readConfig` 不可用）不会触发。
+ *
+ * 这里**不建路由注册表**：权限目录直接由 `app.swagger()` 生成的文档派生（OpenAPI 是唯一来源）。
+ */
+export declare function registerCore(app: FastifyInstance, options: CoreRegistrationOptions): Promise<void>;
+//# sourceMappingURL=assemble.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.d.ts","sourceRoot":"","sources":["../../source/core/assemble.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,eAAe,CAM7D;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CAEvD;AAED,gBAAgB;AAChB,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,QAAQ,EAAE,WAAW,CAAA;IACrB,GAAG,EAAE,SAAS,CAAA;IACd,yEAAyE;IACzE,qBAAqB,CAAC,EAAE,eAAe,CAAA;IACvC,2DAA2D;IAC3D,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CACrC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,GAAG,IAAI,CAIrH;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAOlI;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAWxG"}

package/output/core/assemble.js

@@ -0,0 +1,88 @@
+import Fastify from 'fastify';
+import { registerCookie } from './modules/cookie/index.js';
+import { registerRequestContext } from './modules/context/index.js';
+import { attachServerIdentity } from './modules/identity/index.js';
+import { createLoggerOptions } from './modules/logging/index.js';
+import { registerOpenApi } from './modules/openapi/index.js';
+import { createRequestIdOptions, registerRequestId } from './modules/request-id/index.js';
+import { registerResponse } from './modules/response/index.js';
+import { installRouteSchemaGuard, registerSchema } from './modules/schema/index.js';
+/**
+ * core 步骤 `createFastify`（`prepare`）。
+ *
+ * **总是**建 pino logger（level = `LOG_LEVEL`，默认 `info`） + 内置 `requestId`（入站 `x-request-id`
+ * 复用 / `randomUUID`，日志字段 `requestId`）。`trustProxy: true` 与四家现状一致。
+ *
+ * 固定装配，**不从包对外导出**：对外入口只有 `defineServer` / `startServer` / `generateOpenApi`。
+ */
+export function createFastify(env) {
+    return Fastify({
+        trustProxy: true,
+        logger: createLoggerOptions(env),
+        ...createRequestIdOptions(),
+    });
+}
+/**
+ * 出文档用的**最小实例**（`generateOpenApi` 专用）。
+ *
+ * 没有 logger、没有 `requestId`、没有 `trustProxy`——这些只在**有请求**时才有意义，
+ * 而构建期一条请求都不会发。`logger: false` 下 `app.log` 仍是 `abstract-logging` 的
+ * 空实现，满足 `LoggerLike`，因此下游单元拿到的 `ctx.log` 调用不会炸，也不会产生输出。
+ */
+export function createDocumentFastify() {
+    return Fastify({ logger: false });
+}
+/**
+ * **schema 契约**（固定序，不可替换）：`identity` → `schema`（zod compiler）→ 路由契约守卫。
+ *
+ * 两个入口都必须有它：
+ * - `startServer` 要让 zod 真的校验/序列化请求，并让「路由缺 `schema`」在注册处就失败；
+ * - `generateOpenApi` 要把 zod 转成 JSON Schema 出文档，也要同一个守卫——**文档就是权限目录**，
+ *   构建期放过的路由会在线上变成「接口永远判不过」。
+ *
+ * 单独成函数是为了让「运行期 core」与「文档 core」两条装配路径共用同一段契约，
+ * 而不用把整段运行期能力拖进出文档路径。
+ */
+export function registerSchemaContract(app, options) {
+    attachServerIdentity(app, options.identity);
+    registerSchema(app); // schema → zod compiler
+    installRouteSchemaGuard(app); // 强制所有路由声明 schema（含 operationId / summary / description / tags）
+}
+/**
+ * **文档 core**（`generateOpenApi` 专用）：schema 契约 + swagger。
+ *
+ * 只有这三件事与「把 zod schema 转成 OpenAPI 文档」有关：身份（`info.title` /
+ * `info.version`）、zod compiler（转换前得能读懂 zod）、守卫（不让文档缺条目）、swagger（转换器）。
+ * `requestContext` / `cookie` / `response` / `requestId` 全部**不装**——它们只影响
+ * 请求怎么被处理，而构建期一条请求都不会发。
+ */
+export async function registerDocumentCore(app, options) {
+    registerSchemaContract(app, options);
+    // await：确定性冲刷插件队列，保证 swagger 的 root `onRoute` 钩子在路由注册之前就位
+    await registerOpenApi(app, {
+        title: options.identity.title,
+        version: options.identity.version,
+    });
+}
+/**
+ * core 装配（固定序，不可替换）：`identity` → `schema`（+ 路由契约守卫）→ `requestContext`
+ * → `cookie` → `response` → `openapi` → `requestId` 回吐。
+ *
+ * 全部为框架内置能力，**不暴露选项面**；`request.ctx` 的装配也在这一步完成（`type-augment` 的
+ * 类型承诺因此总有运行期对应物）。**构造期不读配置**（`cookie` 的 domain 在请求期惰性读取），
+ * 故出 spec 路径（`readConfig` 不可用）不会触发。
+ *
+ * 这里**不建路由注册表**：权限目录直接由 `app.swagger()` 生成的文档派生（OpenAPI 是唯一来源）。
+ */
+export async function registerCore(app, options) {
+    registerSchemaContract(app, options);
+    registerRequestContext(app); // request.ctx（type-augment 承诺的运行期对应物）
+    registerCookie(app, { env: options.env, readConfig: options.readConfig });
+    registerResponse(app, { classifyResourceError: options.classifyResourceError });
+    // await：确定性冲刷插件队列，保证 swagger 的 root `onRoute` 钩子在路由注册之前就位
+    await registerOpenApi(app, {
+        title: options.identity.title,
+        version: options.identity.version,
+    });
+    registerRequestId(app); // 响应回吐 x-request-id
+}

package/output/core/boot/context.d.ts

@@ -0,0 +1,109 @@
+import type { ResourceSetupUnit } from './lifecycle.js';
+import type { Disposer } from '@taicode/common-base';
+import type { AppEnv, AppInstance, ClientsContext, ClientsView, ConfigContext, ErrorClassifier, LoggerLike, MiddlewareContext, ResourcesContext, ResourcesView, RouterContext, ServiceContext } from '../types.js';
+/**
+ * 分阶段 ctx 的运行时构造（N1 §2）。
+ *
+ * 每个槽位拿到的是**字段最小集合**的普通对象；`config` 用 getter 暴露，出 spec 路径
+ * （`generateOpenApi` 不跑 `config` 槽位）读到它时抛 `SystemError('CONFIG_UNAVAILABLE')`
+ * —— 让「构造期不得读配置」有运行期护栏，而不仅是文档规则。
+ */
+/**
+ * 运行时镜像 `Live<Value>`：剔除值为 `false` 的键（编译期静态关闭）。
+ *
+ * `resources` 与 `clients` 两个槽位共用这套口径。
+ */
+export declare function liveResources(resources: object): Record<string, unknown>;
+/**
+ * 把 `resources(ctx)` 的返回值拆成「对外视图」与「可执行生命周期列表」。
+ *
+ * 三件事：
+ * - **解包**：`defineResource(client, …)` → 视图里是 `client` 本身；裸对象原样（单元可选）；
+ * - **收集**：有 `setup` / `clean` / `dispose` 的单元按**对象声明序**收集成
+ *   `{ name, setup, clean, dispose }`，分别交给 `setupResourceUnits` / `cleanResourceUnits`
+ *   / `disposeResourceUnits` 执行；
+ * - **剔除**：`false` 键与 `liveResources` 同口径（静态关闭的资源不参与生命周期）。
+ *
+ * ❗识别靠 `'value' in obj && !('then' in obj)`：`Resources` 允许是 Promise（`Awaited<>`
+ * 归一），但**单个资源值本身是 thenable 的极端情况**不当单元——宁可把它当裸值，
+ * 也不要把它错当单元。
+ */
+export declare function splitResourceUnits(resources: object): {
+    view: Record<string, unknown>;
+    units: ResourceSetupUnit[];
+};
+/**
+ * `config` 槽位的**读取能力**（不是容器）。
+ *
+ * 装配期各单元需要的是「能不能读、读到什么」，不是「一个有 `current` 字段的箱子」——
+ * 后者把**写入**也一并交给了每个拿到 `BootContext` 的步骤，绕开 `buildConfig` 就能改配置。
+ * 因此这里只暴露读：`available`（有没有产出）+ `read()`（读，未产出即抛）。
+ *
+ * 写入通道是**私有 Symbol**（本文件内、不导出）：调用方连键名都写不出来，只能通过
+ * `provideConfig()` 写，而它只被 `buildConfig` 调用。
+ */
+export interface ConfigAccess<Config> {
+    /** `config` 槽位是否已产出（出 spec 路径恒为 `false`） */
+    readonly available: boolean;
+    /** 读配置；未产出时抛 `SystemError('CONFIG_UNAVAILABLE')` */
+    read(): Awaited<Config>;
+}
+export declare function createConfigAccess<Config>(): ConfigAccess<Config>;
+/** 写入 `config` 产物（唯一的写入口：由 `buildConfig` 调用，不在 `BootContext` 上暴露） */
+export declare function provideConfig<Config>(access: ConfigAccess<Config>, value: Awaited<Config>): void;
+/** 按**已知键**从配置值里取字段（框架内置单元消费配置的单一入口；不做形状校验） */
+export declare function readConfigKey(config: unknown, key: string): unknown;
+/** `resources(ctx)` 入参 */
+export interface ResourcesContextParams<Env = object> {
+    env: AppEnv<Env>;
+    log: LoggerLike;
+    disposer: Disposer;
+    /** 收集器：`buildResources` 注入，把各资源注册的分类器按注册顺序收起来 */
+    registerClassifyError: (classifier: ErrorClassifier) => void;
+}
+export declare function createResourcesContext<Env = object>(params: ResourcesContextParams<Env>): ResourcesContext<Env>;
+/** `config(ctx)` 入参 */
+export interface ConfigContextParams<Resources, Env = object> {
+    env: AppEnv<Env>;
+    log: LoggerLike;
+    disposer: Disposer;
+    resources: ResourcesView<Resources>;
+}
+export declare function createConfigContext<Resources, Env = object>(params: ConfigContextParams<Resources, Env>): ConfigContext<Resources, Env>;
+/** `clients(ctx)` 入参（与 `services` 同依赖集：`resources` + `config`） */
+export interface ClientsContextParams<Resources, Config> {
+    log: LoggerLike;
+    disposer: Disposer;
+    resources: ResourcesView<Resources>;
+    configAccess: ConfigAccess<Config>;
+}
+export declare function createClientsContext<Resources, Config>(params: ClientsContextParams<Resources, Config>): ClientsContext<Resources, Config>;
+/** `services(ctx)` 入参 */
+export interface ServiceContextParams<Resources, Config, Clients> {
+    log: LoggerLike;
+    disposer: Disposer;
+    resources: ResourcesView<Resources>;
+    configAccess: ConfigAccess<Config>;
+    clients: ClientsView<Clients>;
+}
+export declare function createServiceContext<Resources, Config, Clients>(params: ServiceContextParams<Resources, Config, Clients>): ServiceContext<Resources, Config, Clients>;
+/** `middlewares(ctx)` 入参 */
+export interface MiddlewareContextParams<Config, Services, Clients> {
+    app: AppInstance;
+    log: LoggerLike;
+    disposer: Disposer;
+    services: Awaited<Services>;
+    configAccess: ConfigAccess<Config>;
+    clients: ClientsView<Clients>;
+}
+export declare function createMiddlewareContext<Config, Services, Clients>(params: MiddlewareContextParams<Config, Services, Clients>): MiddlewareContext<Config, Services, Clients>;
+/** `routers(ctx)` 入参 */
+export interface RouterContextParams<Services, Clients> {
+    app: AppInstance;
+    log: LoggerLike;
+    disposer: Disposer;
+    services: Awaited<Services>;
+    clients: ClientsView<Clients>;
+}
+export declare function createRouterContext<Services, Clients>(params: RouterContextParams<Services, Clients>): RouterContext<Services, Clients>;
+//# sourceMappingURL=context.d.ts.map

package/output/core/boot/context.d.ts.map

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

package/output/core/boot/context.js

@@ -0,0 +1,145 @@
+import { SystemError } from '@taicode/common-base';
+/**
+ * 分阶段 ctx 的运行时构造（N1 §2）。
+ *
+ * 每个槽位拿到的是**字段最小集合**的普通对象；`config` 用 getter 暴露，出 spec 路径
+ * （`generateOpenApi` 不跑 `config` 槽位）读到它时抛 `SystemError('CONFIG_UNAVAILABLE')`
+ * —— 让「构造期不得读配置」有运行期护栏，而不仅是文档规则。
+ */
+/**
+ * 运行时镜像 `Live<Value>`：剔除值为 `false` 的键（编译期静态关闭）。
+ *
+ * `resources` 与 `clients` 两个槽位共用这套口径。
+ */
+export function liveResources(resources) {
+    const result = {};
+    for (const [key, value] of Object.entries(resources)) {
+        if (value !== false) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/** 单元外壳的运行时识别（`defineResource` 产物的唯一形状） */
+function isResourceUnit(value) {
+    return typeof value === 'object' && value !== null && 'value' in value && !('then' in value);
+}
+/**
+ * 把 `resources(ctx)` 的返回值拆成「对外视图」与「可执行生命周期列表」。
+ *
+ * 三件事：
+ * - **解包**：`defineResource(client, …)` → 视图里是 `client` 本身；裸对象原样（单元可选）；
+ * - **收集**：有 `setup` / `clean` / `dispose` 的单元按**对象声明序**收集成
+ *   `{ name, setup, clean, dispose }`，分别交给 `setupResourceUnits` / `cleanResourceUnits`
+ *   / `disposeResourceUnits` 执行；
+ * - **剔除**：`false` 键与 `liveResources` 同口径（静态关闭的资源不参与生命周期）。
+ *
+ * ❗识别靠 `'value' in obj && !('then' in obj)`：`Resources` 允许是 Promise（`Awaited<>`
+ * 归一），但**单个资源值本身是 thenable 的极端情况**不当单元——宁可把它当裸值，
+ * 也不要把它错当单元。
+ */
+export function splitResourceUnits(resources) {
+    const view = {};
+    const units = [];
+    for (const [key, value] of Object.entries(resources)) {
+        if (value === false) {
+            continue;
+        }
+        if (isResourceUnit(value)) {
+            view[key] = value.value;
+            const setup = typeof value.setup === 'function' ? value.setup.bind(value) : undefined;
+            const clean = typeof value.clean === 'function' ? value.clean.bind(value) : undefined;
+            const dispose = typeof value.dispose === 'function' ? value.dispose.bind(value) : undefined;
+            if (setup || clean || dispose) {
+                units.push({ name: key, setup, clean, dispose });
+            }
+            continue;
+        }
+        view[key] = value;
+    }
+    return { view, units };
+}
+const CONFIG_WRITE = Symbol('config.write');
+export function createConfigAccess() {
+    let value;
+    const access = {
+        get available() {
+            return value !== undefined;
+        },
+        read() {
+            if (value === undefined) {
+                throw new SystemError('CONFIG_UNAVAILABLE', undefined, '配置尚未就绪（generateOpenApi 路径不跑 config 槽位）：任何单元不得在构造期读配置');
+            }
+            return value;
+        },
+        [CONFIG_WRITE](next) {
+            value = next;
+        },
+    };
+    return access;
+}
+/** 写入 `config` 产物（唯一的写入口：由 `buildConfig` 调用，不在 `BootContext` 上暴露） */
+export function provideConfig(access, value) {
+    const write = access[CONFIG_WRITE];
+    if (write === undefined) {
+        throw new Error('[config] 非法写入：`ConfigAccess` 只能由 `createConfigAccess()` 产出');
+    }
+    write(value);
+}
+/** 按**已知键**从配置值里取字段（框架内置单元消费配置的单一入口；不做形状校验） */
+export function readConfigKey(config, key) {
+    return config?.[key];
+}
+export function createResourcesContext(params) {
+    return {
+        env: params.env,
+        log: params.log,
+        disposer: params.disposer,
+        registerClassifyError: params.registerClassifyError,
+    };
+}
+export function createConfigContext(params) {
+    return { env: params.env, log: params.log, disposer: params.disposer, resources: params.resources };
+}
+export function createClientsContext(params) {
+    return {
+        log: params.log,
+        disposer: params.disposer,
+        resources: params.resources,
+        get config() {
+            return params.configAccess.read();
+        },
+    };
+}
+export function createServiceContext(params) {
+    return {
+        log: params.log,
+        disposer: params.disposer,
+        resources: params.resources,
+        clients: params.clients,
+        get config() {
+            return params.configAccess.read();
+        },
+    };
+}
+export function createMiddlewareContext(params) {
+    return {
+        app: params.app,
+        log: params.log,
+        disposer: params.disposer,
+        services: params.services,
+        clients: params.clients,
+        get config() {
+            return params.configAccess.read();
+        },
+    };
+}
+export function createRouterContext(params) {
+    return {
+        app: params.app,
+        log: params.log,
+        disposer: params.disposer,
+        services: params.services,
+        clients: params.clients,
+    };
+}