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

package/output/app/core/index.d.ts

@@ -1,44 +0,0 @@
-import type { ErrorClassifier } from './response.js';
-import type { ConfigEnv } from '../env.js';
-import type { AppIdentity } from '../types.js';
-import type { FastifyInstance } from 'fastify';
-export { registerCookie, resolveCookieNames, resolveCookieDomain } from './cookie.js';
-export { registerResponse, createSuccessResponse, createErrorResponse } from './response.js';
-export { registerOpenApi, DOC_ROUTE_PREFIX, DOC_SPEC_ROUTE } from './openapi.js';
-export { registerRequestId, REQUEST_ID_HEADER, REQUEST_ID_LOG_LABEL } from './request-id.js';
-export { createLoggerOptions, LOG_REDACT_PATHS } from './logging.js';
-export { SERVER_IDENTITY, attachServerIdentity, readServerIdentity } from './identity.js';
-export type { AuthCookieOptions, CookieCoreOptions } from './cookie.js';
-export type { ResponseCoreOptions, ResponseEnvelope } from './response.js';
-export type { OpenApiCoreOptions } from './openapi.js';
-/**
- * core `schema`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
- *
- * 装配 `fastify-type-provider-zod` 的 validator / serializer compiler；响应 schema 由框架统一
- * 生成（业务侧用 `../schema/index.js` 的 `responseSchema`）。
- */
-export declare function registerSchema(app: FastifyInstance): void;
-/**
- * core 步骤 `createFastify`（`prepare`）。
- *
- * **总是**建 pino logger（level = `LOG_LEVEL`，默认 `info`） + 内置 `requestId`（入站 `x-request-id`
- * 复用 / `randomUUID`，日志字段 `requestId`）。`trustProxy: true` 与四家现状一致。
- */
-export declare function createFastify(env: ConfigEnv): FastifyInstance;
-/** core 装配入参 */
-export interface CoreRegistrationOptions {
-    /** 身份块（`service` / `title` / `version`）：openapi + 内置单元从这里读 */
-    identity: AppIdentity;
-    env: ConfigEnv;
-    /** 数据层错误分类（资源包提供；缺省 = 落 `UNKNOWN_ERROR`） */
-    classifyError?: ErrorClassifier;
-    /** 取**已加载**配置中某个键的访问器（cookie domain 等**惰性**取值；不得在构造期调用） */
-    readConfig: (key: string) => unknown;
-}
-/**
- * core 装配：`schema` → `cookie` → `response` → `openapi` → 路由注册表。
- * `requestId` 的响应回吐 hook 一并注册。**构造期不读配置**（`cookie` 的 domain 在请求期惰性读取），
- * 故出 spec 路径（`readConfig` 不可用）不会触发。
- */
-export declare function registerCore(app: FastifyInstance, options: CoreRegistrationOptions): Promise<void>;
-//# sourceMappingURL=index.d.ts.map

package/output/app/core/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../source/app/core/index.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAC5F,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAChF,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAC5F,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACpE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEzF,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACvE,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAC1E,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEtD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAMzD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,eAAe,CAM7D;AAED,gBAAgB;AAChB,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,QAAQ,EAAE,WAAW,CAAA;IACrB,GAAG,EAAE,SAAS,CAAA;IACd,4CAA4C;IAC5C,aAAa,CAAC,EAAE,eAAe,CAAA;IAC/B,2DAA2D;IAC3D,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CACrC;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAaxG"}

package/output/app/core/index.js

@@ -1,57 +0,0 @@
-import Fastify from 'fastify';
-import { serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
-import { installRegisteredOperations } from '../permission-operations.js';
-import { registerCookie } from './cookie.js';
-import { attachServerIdentity } from './identity.js';
-import { createLoggerOptions } from './logging.js';
-import { registerOpenApi } from './openapi.js';
-import { createRequestIdOptions, registerRequestId } from './request-id.js';
-import { registerResponse } from './response.js';
-export { registerCookie, resolveCookieNames, resolveCookieDomain } from './cookie.js';
-export { registerResponse, createSuccessResponse, createErrorResponse } from './response.js';
-export { registerOpenApi, DOC_ROUTE_PREFIX, DOC_SPEC_ROUTE } from './openapi.js';
-export { registerRequestId, REQUEST_ID_HEADER, REQUEST_ID_LOG_LABEL } from './request-id.js';
-export { createLoggerOptions, LOG_REDACT_PATHS } from './logging.js';
-export { SERVER_IDENTITY, attachServerIdentity, readServerIdentity } from './identity.js';
-/**
- * core `schema`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
- *
- * 装配 `fastify-type-provider-zod` 的 validator / serializer compiler；响应 schema 由框架统一
- * 生成（业务侧用 `../schema/index.js` 的 `responseSchema`）。
- */
-export function registerSchema(app) {
-    app.setValidatorCompiler(validatorCompiler);
-    app.setSerializerCompiler(serializerCompiler);
-}
-/**
- * core 步骤 `createFastify`（`prepare`）。
- *
- * **总是**建 pino logger（level = `LOG_LEVEL`，默认 `info`） + 内置 `requestId`（入站 `x-request-id`
- * 复用 / `randomUUID`，日志字段 `requestId`）。`trustProxy: true` 与四家现状一致。
- */
-export function createFastify(env) {
-    return Fastify({
-        trustProxy: true,
-        logger: createLoggerOptions(env),
-        ...createRequestIdOptions(),
-    });
-}
-/**
- * core 装配：`schema` → `cookie` → `response` → `openapi` → 路由注册表。
- * `requestId` 的响应回吐 hook 一并注册。**构造期不读配置**（`cookie` 的 domain 在请求期惰性读取），
- * 故出 spec 路径（`readConfig` 不可用）不会触发。
- */
-export async function registerCore(app, options) {
-    attachServerIdentity(app, options.identity);
-    registerSchema(app); // schema → zod compiler
-    registerCookie(app, { env: options.env, readConfig: options.readConfig });
-    registerResponse(app, { classifyError: options.classifyError });
-    // await：确定性冲刷插件队列，保证 swagger 的 root `onRoute` 钩子在路由注册之前就位
-    await registerOpenApi(app, {
-        title: options.identity.title,
-        version: options.identity.version,
-    });
-    // 路由注册表：在 routers 阶段之前挂 root `onRoute`，供 `auth` 权限自注册读取（与 swagger 解耦）
-    installRegisteredOperations(app);
-    registerRequestId(app); // 响应回吐 x-request-id
-}

package/output/app/core/logging.d.ts

@@ -1,13 +0,0 @@
-import type { ConfigEnv } from '../env.js';
-import type { FastifyServerOptions } from 'fastify';
-/**
- * core `logging`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
- *
- * `createFastify` **总是**建 pino logger（级别取 `LOG_LEVEL`，默认 `info`）；原 `logging: false`
- * 开关随 `CoreOptions` 一并删除，日志始终开启，不再由 `debug` 控制。
- */
-/** 默认 `redact` 路径（设计 §5.1） */
-export declare const LOG_REDACT_PATHS: readonly ["authorization", "cookie", "set-cookie", "req.headers.authorization", "req.headers.cookie", "*.token", "*.password", "*.secretKey", "*.secretValue"];
-/** 构造 Fastify 的 logger 选项 */
-export declare function createLoggerOptions(env: ConfigEnv): FastifyServerOptions['logger'];
-//# sourceMappingURL=logging.d.ts.map

package/output/app/core/logging.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../../source/app/core/logging.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAEnD;;;;;GAKG;AAEH,8BAA8B;AAC9B,eAAO,MAAM,gBAAgB,gKAUnB,CAAA;AAEV,6BAA6B;AAC7B,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAQlF"}

package/output/app/core/openapi.d.ts

@@ -1,17 +0,0 @@
-import type { FastifyInstance } from 'fastify';
-/**
- * core `openapi`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
- *
- * `@fastify/swagger` + `@scalar/fastify-api-reference`；`/reference` 与 `/reference/openapi.json`；
- * `servers: [{ url: '/' }]`（构建期不依赖 env / DB）；`version` 取 `app.version`（必填，无默认）；
- * `securitySchemes.bearerAuth`；`onListen` 打印实际地址。
- */
-export declare const DOC_ROUTE_PREFIX = "/reference";
-export declare const DOC_SPEC_ROUTE = "/reference/openapi.json";
-export declare const OPENAPI_SPEC_VERSION = "3.0.3";
-export interface OpenApiCoreOptions {
-    title: string;
-    version: string;
-}
-export declare function registerOpenApi(app: FastifyInstance, options: OpenApiCoreOptions): Promise<void>;
-//# sourceMappingURL=openapi.d.ts.map

package/output/app/core/openapi.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../../source/app/core/openapi.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;GAMG;AAEH,eAAO,MAAM,gBAAgB,eAAe,CAAA;AAC5C,eAAO,MAAM,cAAc,4BAA4B,CAAA;AACvD,eAAO,MAAM,oBAAoB,UAAU,CAAA;AAE3C,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BtG"}

package/output/app/core/request-id.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"request-id.d.ts","sourceRoot":"","sources":["../../../source/app/core/request-id.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,iBAAiB,iBAAiB,CAAA;AAC/C,eAAO,MAAM,oBAAoB,cAAc,CAAA;AAE/C,qEAAqE;AACrE,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOpG;AAED,sCAAsC;AACtC,wBAAgB,sBAAsB,IAAI;IACxC,eAAe,EAAE,MAAM,CAAA;IACvB,iBAAiB,EAAE,MAAM,CAAA;IACzB,QAAQ,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;KAAE,KAAK,MAAM,CAAA;CAC1F,CAOA;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAwB5D"}

package/output/app/core/response.d.ts

@@ -1,41 +0,0 @@
-import { SystemError } from '../errors.js';
-import type { FastifyInstance } from 'fastify';
-/**
- * core `response`（设计 §5.1 / §8，错误契约 D7）——**框架内置、锁定、不可替换/修改**。
- *
- * - 成功信封 `{ status: 'SUCCESS', message: 'ok', data }`（由 `preSerialization` 统一包裹）。
- * - 错误信封 `{ status: <错误码字符串>, message, data: null }`。
- * - `setErrorHandler` 固定分支：`UserError`→400（`error.status` 字面量）/ `SystemError`→500 /
- *   zod→400 / serde→500 / 数据层（资源包的 `classifyError`）→500 / 未知→500；**禁止按 `error.type` 细分**。
- * - `setNotFoundHandler` → 404 + `NOT_IMPLEMENTED`（落 `warn`，文案对齐 expense/notice）。
- * - 错误日志分级：`UserError` / zod → `warn`，其余 → `error`（带 stack）。
- * - **错误只给稳定码**（`status` 放错误码字符串），文案不归框架（由前端 / i18n 决定，§10-6）。
- */
-export declare const SUCCESS_STATUS = "SUCCESS";
-export declare const NOT_IMPLEMENTED_STATUS = "NOT_IMPLEMENTED";
-export declare const INVALID_INPUT_STATUS = "INVALID_INPUT";
-export declare const SERIALIZATION_ERROR_STATUS = "RESPONSE_SERIALIZATION_ERROR";
-export declare const UNKNOWN_ERROR_STATUS = "UNKNOWN_ERROR";
-/** 通用兜底文案（仅在 `error.message` 为空时使用） */
-export declare const DEFAULT_USER_MESSAGE = "\u8BF7\u6C42\u5931\u8D25";
-export declare const DEFAULT_SYSTEM_MESSAGE = "\u7CFB\u7EDF\u9519\u8BEF";
-export interface ResponseEnvelope<T> {
-    status: string;
-    message: string;
-    data: T;
-}
-export declare function createSuccessResponse<T>(data: T): ResponseEnvelope<T>;
-export declare function createErrorResponse(status: string, message: string): ResponseEnvelope<null>;
-/**
- * 数据层错误分类器（资源包里带 `classifyError` 的值的裸函数形态）。
- *
- * 资源包（`resources` 槽位返回值）里任何提供 `classifyError` 的值都会被用作响应错误分类；
- * 都没有时错误落 `UNKNOWN_ERROR` 兜底。
- */
-export type ErrorClassifier = (error: unknown) => SystemError | null;
-export interface ResponseCoreOptions {
-    /** Prisma / 数据层错误分类（缺省 = 不做数据层分类） */
-    classifyError?: ErrorClassifier;
-}
-export declare function registerResponse(app: FastifyInstance, options?: ResponseCoreOptions): void;
-//# sourceMappingURL=response.d.ts.map

package/output/app/core/response.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../../source/app/core/response.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAa,MAAM,cAAc,CAAA;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,cAAc,YAAY,CAAA;AACvC,eAAO,MAAM,sBAAsB,oBAAoB,CAAA;AACvD,eAAO,MAAM,oBAAoB,kBAAkB,CAAA;AACnD,eAAO,MAAM,0BAA0B,iCAAiC,CAAA;AACxE,eAAO,MAAM,oBAAoB,kBAAkB,CAAA;AAEnD,uCAAuC;AACvC,eAAO,MAAM,oBAAoB,6BAAS,CAAA;AAC1C,eAAO,MAAM,sBAAsB,6BAAS,CAAA;AAE5C,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,CAAC,CAAA;CACR;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAErE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAE3F;AAsBD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,WAAW,GAAG,IAAI,CAAA;AAEpE,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,aAAa,CAAC,EAAE,eAAe,CAAA;CAChC;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,GAAE,mBAAwB,GAAG,IAAI,CAyD9F"}

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

@@ -1,32 +0,0 @@
-import type { ServerConfig } from './types.js';
-/** #1 `resources` 看不到 `config` */
-export declare function resourcesCannotSeeConfig(): void;
-/** #2 `resources` 看不到 `services` */
-export declare function resourcesCannotSeeServices(): void;
-/** #3 `config` 看不到 `services` */
-export declare function configCannotSeeServices(): void;
-/** #4 `services` 看不到 `services`（禁 service 互依） */
-export declare function servicesCannotSeeServices(): void;
-/** #5 `routers` 看不到 `resources`（禁绕层直连数据层） */
-export declare function routersCannotSeeResources(): void;
-/** #6 `routers` 看不到 `config` */
-export declare function routersCannotSeeConfig(): void;
-/** #7 service 值声明 `dependsOn` → 该值塌成 `never` */
-export declare function serviceValueCannotDeclareDependsOn(): void;
-/** #8 service 值是原始类型 → 被拒（防把配置塞进 services） */
-export declare function serviceValueCannotBePrimitive(): void;
-/** #9 `startServer` 只接受品牌产物，裸 `ServerConfig` 编译失败 */
-export declare function startServerRejectsBareConfig(bare: ServerConfig<unknown, unknown, unknown>): void;
-/** #10 `app.version` 必填 */
-export declare function appVersionIsRequired(): void;
-/** #11 `cache: false` 静态关闭：键被 `Live<>` 从资源视图剔除 */
-export declare function staticallyDisabledResourceIsRemoved(): void;
-/** #12 `config` 看不到 `app` */
-export declare function configCannotSeeApp(): void;
-/** #13 `middlewares` 看不到 `resources`（中间件禁直连数据层） */
-export declare function middlewaresCannotSeeResources(): void;
-/** #14 `middlewares` 看不到 `env` */
-export declare function middlewaresCannotSeeEnv(): void;
-/** #15 `services` 看不到 `env`（服务层禁读 env） */
-export declare function servicesCannotSeeEnv(): void;
-//# sourceMappingURL=define-server.negative-cases.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"define-server.negative-cases.d.ts","sourceRoot":"","sources":["../../source/app/define-server.negative-cases.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAgB9C,kCAAkC;AAClC,wBAAgB,wBAAwB,IAAI,IAAI,CAU/C;AAED,oCAAoC;AACpC,wBAAgB,0BAA0B,IAAI,IAAI,CAUjD;AAED,iCAAiC;AACjC,wBAAgB,uBAAuB,IAAI,IAAI,CAa9C;AAED,iDAAiD;AACjD,wBAAgB,yBAAyB,IAAI,IAAI,CAahD;AAED,6CAA6C;AAC7C,wBAAgB,yBAAyB,IAAI,IAAI,CAYhD;AAED,gCAAgC;AAChC,wBAAgB,sBAAsB,IAAI,IAAI,CAY7C;AAED,gDAAgD;AAChD,wBAAgB,kCAAkC,IAAI,IAAI,CAUzD;AAED,8CAA8C;AAC9C,wBAAgB,6BAA6B,IAAI,IAAI,CAUpD;AAED,qDAAqD;AACrD,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,IAAI,CAGhG;AAED,2BAA2B;AAC3B,wBAAgB,oBAAoB,IAAI,IAAI,CAU3C;AAED,kDAAkD;AAClD,wBAAgB,mCAAmC,IAAI,IAAI,CAa1D;AAED,6BAA6B;AAC7B,wBAAgB,kBAAkB,IAAI,IAAI,CAazC;AAED,mDAAmD;AACnD,wBAAgB,6BAA6B,IAAI,IAAI,CAapD;AAED,kCAAkC;AAClC,wBAAgB,uBAAuB,IAAI,IAAI,CAa9C;AAED,0CAA0C;AAC1C,wBAAgB,oBAAoB,IAAI,IAAI,CAa3C"}

package/output/app/define-server.negative-cases.js

@@ -1,209 +0,0 @@
-import { defineServer, startServer } from './entries.js';
-/**
- * N2 §4 的 **15 条负向用例**：这些写法**必须编译失败**，全部由 `tsc --noEmit` 覆盖
- * （**不进**运行期 vitest 断言）。
- *
- * 文件名刻意**不带** `.test.ts`：它由 `tsc --noEmit` 校验，不被 vitest 当作测试文件执行。
- * 每个用例的 `@ts-expect-error` 必须**确有错误**，否则 tsc 会报「未使用」而失败。
- *
- * 说明：`defineServer` 的调用结果一律不用 —— 这些函数只作编译期证据。
- */
-const identity = { service: 'negative-cases', title: 'Negative Cases', version: '1.0.0' };
-/** #1 `resources` 看不到 `config` */
-export function resourcesCannotSeeConfig() {
-    defineServer({
-        app: identity,
-        // @ts-expect-error `config` 不存在于 ResourcesContext
-        resources: ({ config }) => ({ config }),
-        config: () => ({}),
-        services: () => ({}),
-        middlewares: () => [],
-        routers: () => undefined,
-    });
-}
-/** #2 `resources` 看不到 `services` */
-export function resourcesCannotSeeServices() {
-    defineServer({
-        app: identity,
-        // @ts-expect-error `services` 不存在于 ResourcesContext
-        resources: ({ services }) => ({ services }),
-        config: () => ({}),
-        services: () => ({}),
-        middlewares: () => [],
-        routers: () => undefined,
-    });
-}
-/** #3 `config` 看不到 `services` */
-export function configCannotSeeServices() {
-    defineServer({
-        app: identity,
-        resources: () => ({}),
-        config: (ctx) => {
-            // @ts-expect-error `services` 不存在于 ConfigContext
-            void ctx.services;
-            return {};
-        },
-        services: () => ({}),
-        middlewares: () => [],
-        routers: () => undefined,
-    });
-}
-/** #4 `services` 看不到 `services`（禁 service 互依） */
-export function servicesCannotSeeServices() {
-    defineServer({
-        app: identity,
-        resources: () => ({}),
-        config: () => ({}),
-        services: (ctx) => {
-            // @ts-expect-error `services` 不存在于 ServiceContext（禁互依）
-            void ctx.services;
-            return {};
-        },
-        middlewares: () => [],
-        routers: () => undefined,
-    });
-}
-/** #5 `routers` 看不到 `resources`（禁绕层直连数据层） */
-export function routersCannotSeeResources() {
-    defineServer({
-        app: identity,
-        resources: () => ({ database: {} }),
-        config: () => ({}),
-        services: () => ({}),
-        middlewares: () => [],
-        routers: (ctx) => {
-            // @ts-expect-error `resources` 不存在于 RouterContext
-            void ctx.resources.database;
-        },
-    });
-}
-/** #6 `routers` 看不到 `config` */
-export function routersCannotSeeConfig() {
-    defineServer({
-        app: identity,
-        resources: () => ({}),
-        config: () => ({}),
-        services: () => ({}),
-        middlewares: () => [],
-        routers: (ctx) => {
-            // @ts-expect-error `config` 不存在于 RouterContext
-            void ctx.config;
-        },
-    });
-}
-/** #7 service 值声明 `dependsOn` → 该值塌成 `never` */
-export function serviceValueCannotDeclareDependsOn() {
-    defineServer({
-        app: identity,
-        resources: () => ({}),
-        config: () => ({}),
-        // @ts-expect-error `dependsOn` 声明使该值塌成 never
-        services: () => ({ a: { dependsOn: ['b'] } }),
-        middlewares: () => [],
-        routers: () => undefined,
-    });
-}
-/** #8 service 值是原始类型 → 被拒（防把配置塞进 services） */
-export function serviceValueCannotBePrimitive() {
-    defineServer({
-        app: identity,
-        resources: () => ({}),
-        config: () => ({}),
-        // @ts-expect-error 原始类型值被 ServicesShape 拒绝
-        services: () => ({ count: 1 }),
-        middlewares: () => [],
-        routers: () => undefined,
-    });
-}
-/** #9 `startServer` 只接受品牌产物，裸 `ServerConfig` 编译失败 */
-export function startServerRejectsBareConfig(bare) {
-    // @ts-expect-error 缺 `__brand`，不是 Server
-    void startServer(bare);
-}
-/** #10 `app.version` 必填 */
-export function appVersionIsRequired() {
-    defineServer({
-        // @ts-expect-error `AppIdentity.version` 必填
-        app: { service: 'no-version', title: 'No Version' },
-        resources: () => ({}),
-        config: () => ({}),
-        services: () => ({}),
-        middlewares: () => [],
-        routers: () => undefined,
-    });
-}
-/** #11 `cache: false` 静态关闭：键被 `Live<>` 从资源视图剔除 */
-export function staticallyDisabledResourceIsRemoved() {
-    defineServer({
-        app: identity,
-        resources: () => ({ cache: false, database: { query: () => '' } }),
-        config: (ctx) => {
-            // @ts-expect-error `cache: false` 的键已被 `Live<>` 剔除
-            void ctx.cache;
-            return {};
-        },
-        services: () => ({}),
-        middlewares: () => [],
-        routers: () => undefined,
-    });
-}
-/** #12 `config` 看不到 `app` */
-export function configCannotSeeApp() {
-    defineServer({
-        app: identity,
-        resources: () => ({}),
-        config: (ctx) => {
-            // @ts-expect-error `app` 不存在于 ConfigContext
-            void ctx.app;
-            return {};
-        },
-        services: () => ({}),
-        middlewares: () => [],
-        routers: () => undefined,
-    });
-}
-/** #13 `middlewares` 看不到 `resources`（中间件禁直连数据层） */
-export function middlewaresCannotSeeResources() {
-    defineServer({
-        app: identity,
-        resources: () => ({ database: {} }),
-        config: () => ({}),
-        services: () => ({}),
-        middlewares: (ctx) => {
-            // @ts-expect-error `resources` 不存在于 MiddlewareContext
-            void ctx.resources.database;
-            return [];
-        },
-        routers: () => undefined,
-    });
-}
-/** #14 `middlewares` 看不到 `env` */
-export function middlewaresCannotSeeEnv() {
-    defineServer({
-        app: identity,
-        resources: () => ({}),
-        config: () => ({}),
-        services: () => ({}),
-        middlewares: (ctx) => {
-            // @ts-expect-error `env` 不存在于 MiddlewareContext
-            void ctx.env;
-            return [];
-        },
-        routers: () => undefined,
-    });
-}
-/** #15 `services` 看不到 `env`（服务层禁读 env） */
-export function servicesCannotSeeEnv() {
-    defineServer({
-        app: identity,
-        resources: () => ({}),
-        config: () => ({}),
-        services: (ctx) => {
-            // @ts-expect-error `env` 不存在于 ServiceContext
-            void ctx.env.DATABASE_URL;
-            return {};
-        },
-        middlewares: () => [],
-        routers: () => undefined,
-    });
-}

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

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

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

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

package/output/app/define-server.test.js

@@ -1,97 +0,0 @@
-import { describe, expect, expectTypeOf, it } from 'vitest';
-import { defineServer, isServer, SERVER_BRAND, generateOpenApi } from './entries.js';
-/**
- * `defineServer()`（N1 §1）——**纯定义**：产出一个 `Server` 对象，不建连、不起服务。
- *
- * 同一份定义可同时喂给「启动」与「出 spec」，这也是 `mode` 消失的原因。
- */
-describe('defineServer 纯定义（N1 §1）', () => {
-    it('返回带品牌字段的 Server，并原样保留六个槽位', () => {
-        let resourcesCalls = 0;
-        const config = {
-            app: { service: 'define-server-test', title: 'Define Server Test', version: '1.0.0' },
-            resources: () => {
-                resourcesCalls += 1;
-                return {};
-            },
-            config: () => ({ enabled: true }),
-            services: () => ({}),
-            middlewares: () => [],
-            routers: () => undefined,
-        };
-        const server = defineServer(config);
-        expect(server.__brand).toBe(SERVER_BRAND);
-        expect(server.app).toEqual({ service: 'define-server-test', title: 'Define Server Test', version: '1.0.0' });
-        expect(server.services).toBe(config.services);
-        expect(server.routers).toBe(config.routers);
-        // 纯定义：不跑任何工厂
-        expect(resourcesCalls).toBe(0);
-    });
-    it('isServer 只识别 defineServer 产物', () => {
-        const server = defineServer({
-            app: { service: 'is-server-test', title: 'Is Server Test', version: '1.0.0' },
-            resources: () => ({}),
-            config: () => ({}),
-            services: () => ({}),
-            middlewares: () => [],
-            routers: () => undefined,
-        });
-        expect(isServer(server)).toBe(true);
-        expect(isServer({ __brand: 'other' })).toBe(false);
-        expect(isServer(null)).toBe(false);
-        expect(isServer('taicode.server')).toBe(false);
-    });
-    it('定义产物三入口共用：generateOpenApi 只读定义，不跑 config 槽位', async () => {
-        let configCalls = 0;
-        const server = defineServer({
-            app: { service: 'define-shared', title: 'Define Shared', version: '1.0.0' },
-            resources: () => ({}),
-            config: () => {
-                configCalls += 1;
-                return {};
-            },
-            services: () => ({}),
-            middlewares: () => [],
-            routers: () => undefined,
-        });
-        await generateOpenApi(server);
-        expect(configCalls).toBe(0);
-    });
-    it('app.version 必填：缺 version 时 TypeScript 编译失败（无默认值）', () => {
-        // 纯类型约束：这里只靠 `tsc --noEmit` 校验。若 `version` 又变回可选，
-        // `@ts-expect-error` 会因「未使用」而报错，测试反而变红。
-        const build = () => ({
-            // @ts-expect-error 缺少必填 app.version
-            app: { service: 'missing-version', title: 'Missing Version' },
-            resources: () => ({}),
-            config: () => ({}),
-            services: () => ({}),
-            middlewares: () => [],
-            routers: () => undefined,
-        });
-        expect(build).toBeTypeOf('function');
-    });
-    it('R / C / S 全推导：middlewares 与 routers 的 ctx.services 是强类型实体（M5）', () => {
-        defineServer({
-            app: { service: 'infer', title: 'Infer', version: '1.0.0' },
-            resources: () => ({ database: { query: (sql) => sql } }),
-            config: ({ resources }) => ({ domain: resources.database.query('domain') }),
-            services: ({ resources, config }) => ({
-                user: {
-                    find: (id) => `${config.domain}:${resources.database.query(id)}`,
-                },
-            }),
-            middlewares: (ctx) => {
-                // 类型自证：ctx.services 是 services 的返回类型（不是 unknown）
-                expectTypeOf(ctx.services.user.find).toEqualTypeOf();
-                // 类型自证：ctx.config 是 config 的返回类型
-                expectTypeOf(ctx.config.domain).toEqualTypeOf();
-                return [];
-            },
-            routers: (ctx) => {
-                expectTypeOf(ctx.services.user.find).toEqualTypeOf();
-                ctx.app.get('/user', () => ({ name: ctx.services.user.find('1') }));
-            },
-        });
-    });
-});

package/output/app/entries.d.ts

@@ -1,29 +0,0 @@
-import type { OpenApiDocument, Server, ServerConfig, StartServerOptions } from './types.js';
-import type { FastifyInstance } from 'fastify';
-export { SERVER_BRAND } from './types.js';
-/**
- * `defineServer()`（N1 §1）——**纯定义**：产出一个 `Server` 对象，不建连、不起服务。
- *
- * 启动是另一个函数（`startServer`）的事——同一份定义可同时喂给「启动」与「出 spec」
- * （`generateOpenApi`）。调用方**不写泛型**：`R` / `C` / `S` 全部从工厂返回类型推导。
- */
-export declare function defineServer<R, C, S>(config: ServerConfig<R, C, S>): Server<R, C, S>;
-/** 供内部/调试使用：判断是否为 `defineServer()` 产物 */
-export declare function isServer(value: unknown): value is Server<unknown, unknown, unknown>;
-/**
- * `startServer()`——真正跑起来：构造资源、加载配置、建服务、装中间件、注册路由、listen、装信号。
- *
- * - 最早阶段**固定加载 env**（`.env.dev < .env < .env.local`；`ENV=test` 追加 `.env.test.local`）。
- * - 返回**原生 `FastifyInstance`**：不包 `fastify-plugin`、不返回包装对象。
- * - `listen` 默认 `NODE_ENV !== 'test'`（测试不监听）。
- * - 硬性要求 `Server`（品牌）产物：传裸 `ServerConfig` 是编译错误。
- */
-export declare function startServer<R, C, S>(server: Server<R, C, S>, options?: StartServerOptions<R, C, S>): Promise<FastifyInstance>;
-/**
- * `generateOpenApi()`——只出 spec，跑到能拿到 schema 就停。
- *
- * **红线**：全程**不得要求配置有效** —— 不跑 `config` 槽位、不要求 `DATABASE_URL` / `REDIS_URL`
- * 有效；`resources`（只构造不建连）/ `services` / 中间件注册 / 路由注册照常执行。
- */
-export declare function generateOpenApi<R, C, S>(server: Server<R, C, S>): Promise<OpenApiDocument>;
-//# sourceMappingURL=entries.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../source/app/entries.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEzC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAMpF;AAED,yCAAyC;AACzC,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAMnF;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,GAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAavI;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,CAiBhG"}

package/output/app/entries.js

@@ -1,64 +0,0 @@
-import { bootServer, BOOT_PHASE_OPENAPI, BOOT_PHASE_START } from './boot.js';
-import { loadRuntimeEnvFiles, resolveConfigEnv } from './env.js';
-import { SERVER_BRAND } from './types.js';
-export { SERVER_BRAND } from './types.js';
-/**
- * `defineServer()`（N1 §1）——**纯定义**：产出一个 `Server` 对象，不建连、不起服务。
- *
- * 启动是另一个函数（`startServer`）的事——同一份定义可同时喂给「启动」与「出 spec」
- * （`generateOpenApi`）。调用方**不写泛型**：`R` / `C` / `S` 全部从工厂返回类型推导。
- */
-export function defineServer(config) {
-    const server = {
-        ...config,
-        __brand: SERVER_BRAND,
-    };
-    return server;
-}
-/** 供内部/调试使用：判断是否为 `defineServer()` 产物 */
-export function isServer(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        value.__brand === SERVER_BRAND);
-}
-/**
- * `startServer()`——真正跑起来：构造资源、加载配置、建服务、装中间件、注册路由、listen、装信号。
- *
- * - 最早阶段**固定加载 env**（`.env.dev < .env < .env.local`；`ENV=test` 追加 `.env.test.local`）。
- * - 返回**原生 `FastifyInstance`**：不包 `fastify-plugin`、不返回包装对象。
- * - `listen` 默认 `NODE_ENV !== 'test'`（测试不监听）。
- * - 硬性要求 `Server`（品牌）产物：传裸 `ServerConfig` 是编译错误。
- */
-export async function startServer(server, options = {}) {
-    const env = loadRuntimeEnvFiles();
-    const isTest = process.env.NODE_ENV === 'test';
-    const booted = await bootServer({
-        server,
-        env,
-        phase: BOOT_PHASE_START,
-        listen: options.listen ?? !isTest,
-        shutdown: options.shutdown,
-    });
-    return booted.app;
-}
-/**
- * `generateOpenApi()`——只出 spec，跑到能拿到 schema 就停。
- *
- * **红线**：全程**不得要求配置有效** —— 不跑 `config` 槽位、不要求 `DATABASE_URL` / `REDIS_URL`
- * 有效；`resources`（只构造不建连）/ `services` / 中间件注册 / 路由注册照常执行。
- */
-export async function generateOpenApi(server) {
-    // 不加载 .env 文件、不读配置
-    const env = resolveConfigEnv();
-    const booted = await bootServer({
-        server,
-        env,
-        phase: BOOT_PHASE_OPENAPI,
-        listen: false,
-    });
-    const app = booted.app;
-    if (typeof app.swagger !== 'function') {
-        throw new Error('[generateOpenApi] @fastify/swagger is not registered');
-    }
-    return app.swagger();
-}