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

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

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

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

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

package/output/app/auth.test.js

@@ -0,0 +1,148 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { defineServer, startServer } from './entries.js';
+import { createAuthMiddleware } from './middleware/auth.js';
+import { createContextMiddleware } from './middleware/context.js';
+const listWidgetSchema = { operationId: 'listWidget' };
+const widgetDetailSchema = { operationId: 'getWidgetDetail' };
+function captureVerify(capture) {
+    return async (input) => {
+        capture.push(input);
+        return { user: { id: 'user-1' }, token: input.token };
+    };
+}
+function createServer(configuration, authOptions = {}) {
+    return defineServer({
+        app: { service: 'auth', title: 'Auth', version: '1.0.0' },
+        resources: () => ({}),
+        config: () => configuration,
+        services: () => ({}),
+        middlewares: (ctx) => [
+            createContextMiddleware(),
+            createAuthMiddleware(ctx, { registerPermissions: false, ...authOptions }),
+        ],
+        routers: (ctx) => {
+            ctx.app.get('/widget/with-operation', { schema: listWidgetSchema }, () => ({ ok: true }));
+            ctx.app.get('/widget/no-operation', () => ({ ok: true }));
+            ctx.app.get('/widget/:id/detail', { schema: widgetDetailSchema }, () => ({ ok: true }));
+        },
+    });
+}
+const bearerToken = ['Bearer', 'token-1'].join(' ');
+async function request(app, url, headers = {}) {
+    const response = await app.inject({
+        method: 'GET',
+        url,
+        headers: { authorization: bearerToken, ...headers },
+    });
+    expect(response.statusCode).toBe(200);
+}
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+describe('auth verify 入参', () => {
+    it('operation 优先取路由 schema.operationId，未声明时回落 url；service 取身份块', async () => {
+        const capture = [];
+        const app = await startServer(createServer({ account: { enabled: true, serviceUrl: 'http://account.local' } }, { verify: captureVerify(capture) }), { listen: false });
+        try {
+            await request(app, '/widget/with-operation');
+            await request(app, '/widget/no-operation');
+            expect(capture.map((input) => input.operation)).toEqual(['listWidget', '/widget/no-operation']);
+            expect(capture.map((input) => input.service)).toEqual(['auth', 'auth']);
+        }
+        finally {
+            await app.close();
+        }
+    });
+});
+describe('resource / metadata', () => {
+    it('resource 取路由参数、metadata 填请求元信息', async () => {
+        const capture = [];
+        const app = await startServer(createServer({ account: { enabled: true, serviceUrl: 'http://account.local' } }, { verify: captureVerify(capture) }), { listen: false });
+        try {
+            await request(app, '/widget/w-9/detail', { 'user-agent': 'auth-test-agent' });
+            const input = capture[0];
+            expect(input.resource).toEqual({ id: 'w-9' });
+            expect(input.metadata).toMatchObject({
+                method: 'GET',
+                url: '/widget/w-9/detail',
+                userAgent: 'auth-test-agent',
+            });
+            expect(typeof input.metadata?.requestId).toBe('string');
+            expect(typeof input.metadata?.ip).toBe('string');
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('内置 verify 的 POST body 一并带上 resource 与 metadata', async () => {
+        const requests = [];
+        const fetchStub = vi.fn(async (input, init) => {
+            requests.push({
+                url: typeof input === 'string' ? input : input.toString(),
+                body: init?.body ? JSON.parse(String(init.body)) : undefined,
+            });
+            return {
+                ok: true,
+                status: 200,
+                json: async () => ({ status: 'SUCCESS', data: { user: { id: 'u' }, token: 'token-1' } }),
+            };
+        });
+        vi.stubGlobal('fetch', fetchStub);
+        const app = await startServer(createServer({ account: { enabled: true, serviceUrl: 'http://account.local' } }), { listen: false });
+        try {
+            await request(app, '/widget/w-9/detail', { 'user-agent': 'auth-test-agent' });
+            expect(requests).toHaveLength(1);
+            expect(requests[0].url).toBe('http://account.local/gateway/verify');
+            expect(requests[0].body?.operation).toBe('getWidgetDetail');
+            expect(requests[0].body?.resource).toEqual({ id: 'w-9' });
+            expect(requests[0].body?.metadata).toMatchObject({
+                method: 'GET',
+                url: '/widget/w-9/detail',
+                userAgent: 'auth-test-agent',
+            });
+        }
+        finally {
+            await app.close();
+        }
+    });
+});
+describe('account serviceUrl 门槛仅作用于内置 verify', () => {
+    it('自定义 verify + account 无 serviceUrl 时仍然校验', async () => {
+        const capture = [];
+        const app = await startServer(createServer({ account: { enabled: false } }, { verify: captureVerify(capture) }), { listen: false });
+        try {
+            await request(app, '/widget/with-operation');
+            expect(capture.map((input) => input.operation)).toEqual(['listWidget']);
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('内置 verify + account 无 serviceUrl 时放行（不校验、不发请求）', async () => {
+        const fetchStub = vi.fn(async () => {
+            throw new Error('should not be called');
+        });
+        vi.stubGlobal('fetch', fetchStub);
+        const app = await startServer(createServer({ account: { enabled: false } }), { listen: false });
+        try {
+            // 无凭证也 200：无 serviceUrl 时内置 verify 直接放行
+            await request(app, '/widget/with-operation', { authorization: '' });
+            expect(fetchStub).not.toHaveBeenCalled();
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('跳过 docPath / OPTIONS / NoLoginRequired（默认 skip）', async () => {
+        const capture = [];
+        const app = await startServer(createServer({ account: { enabled: true, serviceUrl: 'http://account.local' } }, { verify: captureVerify(capture) }), { listen: false });
+        try {
+            const optionsResponse = await app.inject({ method: 'OPTIONS', url: '/widget/with-operation' });
+            expect(optionsResponse.statusCode).not.toBe(500);
+            expect(capture).toHaveLength(0);
+        }
+        finally {
+            await app.close();
+        }
+    });
+});

package/output/app/boot.d.ts

@@ -0,0 +1,48 @@
+import type { ErrorClassifier } from './core/response.js';
+import type { ConfigEnv } from './env.js';
+import type { ResourcesView, Server, ShutdownContext } from './types.js';
+import type { FastifyInstance } from 'fastify';
+/** 内部步序（`prepare` → `compose` → `activate`）：`startServer` / `generateOpenApi` 共用。 */
+export declare const BOOT_PHASE_START = "start";
+export declare const BOOT_PHASE_OPENAPI = "openapi";
+/** 两个入口的内部步序跳过集 */
+export type BootPhase = typeof BOOT_PHASE_START | typeof BOOT_PHASE_OPENAPI;
+/** 默认监听地址 */
+export declare const DEFAULT_HOST = "0.0.0.0";
+export interface BootInput<R, C, S> {
+    server: Server<R, C, S>;
+    env: ConfigEnv;
+    phase: BootPhase;
+    listen: boolean;
+    shutdown?: (ctx: ShutdownContext<R, C, S>) => Promise<void>;
+}
+export interface BootedServer<R, S> {
+    app: FastifyInstance;
+    resources: ResourcesView<R>;
+    services: Awaited<S>;
+    dispose: () => Promise<void>;
+}
+/**
+ * 资源包里的数据层错误分类器。
+ *
+ * 约定：`resources(ctx)` 返回的资源包里**任一**提供 `classifyError` 函数的值都会被用上
+ * （框架不提供数据层 helper；由服务仓在资源包里自行提供一个带 `classifyError` 的值）。
+ * 都没有 → 返回 `undefined`，响应层落 `UNKNOWN_ERROR` 兜底。
+ */
+export declare function resolveErrorClassifier(resources: Record<string, unknown>): ErrorClassifier | undefined;
+/**
+ * 装配一个服务（`startServer` / `generateOpenApi` 共用）。
+ *
+ * 步序（N1 §5）：
+ * ```
+ * 1. 加载 env（框架固定，调用方已做）        → env
+ * 2. resources(ctx={env,log})                → R（只构造，不建连）
+ * 3. config(ctx={env,log,resources})         → C（仅 start 路径；出 spec 路径不跑）
+ * 4. services(ctx={log,disposer,resources,config}) → S，随后按声明序 init()（仅 start 路径）
+ * 5. middlewares(ctx={app,log,services,config})    → 按数组序 register(app)
+ * 6. routers(ctx={app,log,services})               → 注册路由
+ * 7. ready / listen
+ * ```
+ */
+export declare function bootServer<R, C, S>(input: BootInput<R, C, S>): Promise<BootedServer<R, S>>;
+//# sourceMappingURL=boot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../source/app/boot.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACrF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,qFAAqF;AACrF,eAAO,MAAM,gBAAgB,UAAU,CAAA;AACvC,eAAO,MAAM,kBAAkB,YAAY,CAAA;AAC3C,mBAAmB;AACnB,MAAM,MAAM,SAAS,GAAG,OAAO,gBAAgB,GAAG,OAAO,kBAAkB,CAAA;AAC3E,aAAa;AACb,eAAO,MAAM,YAAY,YAAY,CAAA;AAErC,MAAM,WAAW,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAA;IACvB,GAAG,EAAE,SAAS,CAAA;IACd,KAAK,EAAE,SAAS,CAAA;IAChB,MAAM,EAAE,OAAO,CAAA;IACf,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5D;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,EAAE,CAAC;IAChC,GAAG,EAAE,eAAe,CAAA;IACpB,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;IAC3B,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IACpB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAcD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,GAAG,SAAS,CAOtG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAkGhG"}

package/output/app/boot.js

@@ -0,0 +1,123 @@
+import { Disposer } from '@taicode/common-base';
+import { createConfigContext, createConfigHolder, createMiddlewareContext, createResourcesContext, createRouterContext, createServiceContext, createShutdownContext, liveResources, readConfigKey, requireConfig, } from './context.js';
+import { createFastify, registerCore } from './core/index.js';
+import { disposeServices, initServiceUnits, MIDDLEWARES_LOG_STAGE, middlewareUnitName } from './lifecycle.js';
+import { runShutdown } from './shutdown.js';
+import { attachSignalHandlers } from './signal.js';
+/** 内部步序（`prepare` → `compose` → `activate`）：`startServer` / `generateOpenApi` 共用。 */
+export const BOOT_PHASE_START = 'start';
+export const BOOT_PHASE_OPENAPI = 'openapi';
+/** 默认监听地址 */
+export const DEFAULT_HOST = '0.0.0.0';
+function resolvePort(env) {
+    const parsed = Number(env.API_PORT);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`[server] API_PORT is required to listen (got "${env.API_PORT}")`);
+    }
+    return parsed;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * 资源包里的数据层错误分类器。
+ *
+ * 约定：`resources(ctx)` 返回的资源包里**任一**提供 `classifyError` 函数的值都会被用上
+ * （框架不提供数据层 helper；由服务仓在资源包里自行提供一个带 `classifyError` 的值）。
+ * 都没有 → 返回 `undefined`，响应层落 `UNKNOWN_ERROR` 兜底。
+ */
+export function resolveErrorClassifier(resources) {
+    for (const value of Object.values(resources)) {
+        if (isRecord(value) && typeof value.classifyError === 'function') {
+            return (error) => value.classifyError(error);
+        }
+    }
+    return undefined;
+}
+/**
+ * 装配一个服务（`startServer` / `generateOpenApi` 共用）。
+ *
+ * 步序（N1 §5）：
+ * ```
+ * 1. 加载 env（框架固定，调用方已做）        → env
+ * 2. resources(ctx={env,log})                → R（只构造，不建连）
+ * 3. config(ctx={env,log,resources})         → C（仅 start 路径；出 spec 路径不跑）
+ * 4. services(ctx={log,disposer,resources,config}) → S，随后按声明序 init()（仅 start 路径）
+ * 5. middlewares(ctx={app,log,services,config})    → 按数组序 register(app)
+ * 6. routers(ctx={app,log,services})               → 注册路由
+ * 7. ready / listen
+ * ```
+ */
+export async function bootServer(input) {
+    const { server, env, phase } = input;
+    const isStart = phase === BOOT_PHASE_START;
+    const service = server.app.service;
+    // ── prepare ──────────────────────────────────────────────────────────────
+    // ① createFastify（+ 内置 logger / requestId）
+    const app = createFastify(env);
+    const instance = app;
+    const log = app.log;
+    const disposer = new Disposer();
+    const holder = createConfigHolder();
+    // ② resources：只构造，不建连（出 spec 路径同样执行）
+    const resources = (await server.resources(createResourcesContext({ env, log })));
+    const resourcesView = liveResources(resources);
+    // ③ core 装配（schema → cookie → response → openapi → 路由注册表）
+    await registerCore(app, {
+        identity: server.app,
+        env,
+        classifyError: resolveErrorClassifier(resourcesView),
+        readConfig: (key) => readConfigKey(requireConfig(holder), key),
+    });
+    // ── compose ──────────────────────────────────────────────────────────────
+    // ① config（仅 start 路径；出 spec 路径不跑 → `ctx.config` 读到即抛 CONFIG_UNAVAILABLE）
+    if (isStart) {
+        holder.current = (await server.config(createConfigContext({ env, log, resources: resourcesView })));
+    }
+    // ② services（两个入口都执行；ctx 无 env、无 services）
+    const services = server.services(createServiceContext({
+        log,
+        disposer,
+        resources: resourcesView,
+        holder,
+    }));
+    // ③ initLifecycleUnits（仅 start 路径）
+    if (isStart) {
+        await initServiceUnits({ service, log, services: services });
+    }
+    // ④ middlewares（两个入口都执行：出 spec 也照注册，保证 schema 一致）
+    const middlewares = server.middlewares(createMiddlewareContext({ app: instance, log, services, holder }));
+    for (const [index, unit] of middlewares.entries()) {
+        await unit.register(instance);
+        log.debug({ service, unit: middlewareUnitName(service, unit, index), stage: MIDDLEWARES_LOG_STAGE }, '[middleware] registered');
+    }
+    // ⑤ routers（两个入口都执行）
+    await server.routers(createRouterContext({ app: instance, log, services }));
+    // ── activate ─────────────────────────────────────────────────────────────
+    const runShutdownFlow = async () => {
+        if (input.shutdown) {
+            await input.shutdown(createShutdownContext({
+                app: instance,
+                log,
+                disposer,
+                resources: resourcesView,
+                holder,
+                services,
+            }));
+            return;
+        }
+        await runShutdown({
+            stopProducers: () => disposer.dispose(),
+            disposeServices: () => disposeServices({ service, log, services: services }),
+        }, log);
+    };
+    app.addHook('onClose', () => runShutdownFlow());
+    // ⑥ ready（两个入口都执行）
+    await app.ready();
+    // ⑦ listen / signal（仅 start 路径）
+    if (isStart && input.listen) {
+        await app.listen({ port: resolvePort(env), host: DEFAULT_HOST });
+        attachSignalHandlers(app, log);
+    }
+    return { app, resources: resourcesView, services, dispose: runShutdownFlow };
+}

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

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

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

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

package/output/app/config.test.js

@@ -0,0 +1,132 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { defineServer, generateOpenApi, startServer } from './entries.js';
+import { SystemError, UserError } from './errors.js';
+const rows = { 'server.domain': 'example.com' };
+const fakeDatabase = {
+    get: (key) => Promise.resolve(rows[key]),
+};
+describe('config 槽位（N1 §2 / N2 §2.4）', () => {
+    it('① 入参含 env/log/resources，且不含 config/services/app', async () => {
+        const captured = [];
+        const server = defineServer({
+            app: { service: 'config-test', title: 'Config Test', version: '1.0.0' },
+            resources: () => ({ database: fakeDatabase }),
+            config: (ctx) => {
+                captured.push(ctx);
+                return { domain: 'example.com' };
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        const app = await startServer(server, { listen: false });
+        try {
+            expect(captured).toHaveLength(1);
+            const ctx = captured[0];
+            expect('config' in ctx).toBe(false);
+            expect('services' in ctx).toBe(false);
+            expect('app' in ctx).toBe(false);
+            expect(ctx.resources.database).toBe(fakeDatabase);
+            expect(typeof ctx.log.info).toBe('function');
+            expect(Object.keys(ctx.env).sort()).toEqual([
+                'API_PORT',
+                'DATABASE_URL',
+                'ENV',
+                'LOG_LEVEL',
+                'REDIS_URL',
+            ]);
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('② 可从「库」读配置：`services` / `middlewares` 经 `ctx.config` 拿到值', async () => {
+        let domainInServices;
+        let domainInMiddlewares;
+        const server = defineServer({
+            app: { service: 'config-from-database', title: 'Config From Database', version: '1.0.0' },
+            resources: () => ({ database: fakeDatabase }),
+            config: async (ctx) => ({ domain: (await ctx.resources.database.get('server.domain')) ?? '' }),
+            services: (ctx) => {
+                domainInServices = ctx.config.domain;
+                return {};
+            },
+            middlewares: (ctx) => {
+                domainInMiddlewares = ctx.config.domain;
+                return [];
+            },
+            routers: (ctx) => {
+                ctx.app.get('/domain', () => ({ domain: ctx.services === null ? '' : 'ok' }));
+            },
+        });
+        const app = await startServer(server, { listen: false });
+        try {
+            expect(domainInServices).toBe('example.com');
+            expect(domainInMiddlewares).toBe('example.com');
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('③ 同一份定义：startServer 跑 config，generateOpenApi 不跑（红线）', async () => {
+        let calls = 0;
+        const server = defineServer({
+            app: { service: 'config-redline', title: 'Config Red Line', version: '1.0.0' },
+            resources: () => ({ database: fakeDatabase }),
+            config: () => {
+                calls += 1;
+                return {};
+            },
+            services: () => ({}),
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        await generateOpenApi(server);
+        expect(calls).toBe(0);
+        const app = await startServer(server, { listen: false });
+        expect(calls).toBe(1);
+        await app.close();
+    });
+    it('④ 出 spec 路径：services 读 ctx.config 抛 CONFIG_UNAVAILABLE（构造期不得读配置）', async () => {
+        const server = defineServer({
+            app: { service: 'config-openapi', title: 'Config OpenApi', version: '1.0.0' },
+            resources: () => ({}),
+            config: () => ({ domain: 'spec' }),
+            services: (ctx) => {
+                // 构造期不得读配置；出 spec 路径上读到即抛
+                void ctx.config;
+                return {};
+            },
+            middlewares: () => [],
+            routers: () => undefined,
+        });
+        let caught;
+        try {
+            await generateOpenApi(server);
+        }
+        catch (error) {
+            caught = error;
+        }
+        expect(SystemError.is(caught)).toBe(true);
+        expect(caught.type).toBe('CONFIG_UNAVAILABLE');
+    });
+    it('⑤ `UserError` / `SystemError` 的 `status` 是字面量、`is()` 走品牌（N2 §2.12）', () => {
+        const user = new UserError('INVALID_TOKEN', undefined, 'boom');
+        const system = new SystemError('DATABASE_ERROR', undefined, 'boom');
+        // `status` 是字面量类型（改错直接编译失败）
+        expectTypeOf(user.status).toEqualTypeOf();
+        expectTypeOf(system.status).toEqualTypeOf();
+        expect(user.type).toBe('INVALID_TOKEN');
+        expect(user.status).toBe(400);
+        expect(system.status).toBe(500);
+        // `is()` 走 `Symbol.for` 品牌：**不用 `instanceof`**，原型链丢失也能识别
+        const plainUserError = Object.assign(Object.create(null), {
+            type: 'INVALID_TOKEN',
+            message: 'boom',
+        });
+        Object.defineProperty(plainUserError, Symbol.for('@taicode/common/UserError'), { value: true });
+        expect(UserError.is(plainUserError)).toBe(true);
+        expect(SystemError.is(plainUserError)).toBe(false);
+        expect(UserError.is(new Error('boom'))).toBe(false);
+    });
+});

package/output/app/context.d.ts

@@ -0,0 +1,68 @@
+import type { Disposer } from '@taicode/common-base';
+import type { ConfigEnv } from './env.js';
+import type { AppInstance, ConfigContext, LoggerLike, MiddlewareContext, ResourcesContext, ResourcesView, RouterContext, ServiceContext, ShutdownContext } from './types.js';
+/**
+ * 分阶段 ctx 的运行时构造（N1 §2）。
+ *
+ * 每个槽位拿到的是**字段最小集合**的普通对象；`config` 用 getter 暴露，出 spec 路径
+ * （`generateOpenApi` 不跑 `config` 槽位）读到它时抛 `SystemError('CONFIG_UNAVAILABLE')`
+ * —— 让「构造期不得读配置」有运行期护栏，而不仅是文档规则。
+ */
+/** 运行时镜像 `Live<T>`：剔除值为 `false` 的键（编译期静态关闭） */
+export declare function liveResources(resources: object): Record<string, unknown>;
+/** `config` 槽位产物持有者（`startServer` 路径写入；出 spec 路径留空） */
+export interface ConfigHolder<C> {
+    current: Awaited<C> | undefined;
+}
+export declare function createConfigHolder<C>(): ConfigHolder<C>;
+/** 读配置：react 未就绪时抛 `SystemError('CONFIG_UNAVAILABLE')` */
+export declare function requireConfig<C>(holder: ConfigHolder<C>): Awaited<C>;
+/** 按**已知键**从配置值里取字段（框架内置单元消费配置的单一入口；不做形状校验） */
+export declare function readConfigKey(config: unknown, key: string): unknown;
+/** `resources(ctx)` 入参 */
+export interface ResourcesContextParams {
+    env: ConfigEnv;
+    log: LoggerLike;
+}
+export declare function createResourcesContext(params: ResourcesContextParams): ResourcesContext;
+/** `config(ctx)` 入参 */
+export interface ConfigContextParams<R> {
+    env: ConfigEnv;
+    log: LoggerLike;
+    resources: ResourcesView<R>;
+}
+export declare function createConfigContext<R>(params: ConfigContextParams<R>): ConfigContext<R>;
+/** `services(ctx)` 入参 */
+export interface ServiceContextParams<R, C> {
+    log: LoggerLike;
+    disposer: Disposer;
+    resources: ResourcesView<R>;
+    holder: ConfigHolder<C>;
+}
+export declare function createServiceContext<R, C>(params: ServiceContextParams<R, C>): ServiceContext<R, C>;
+/** `middlewares(ctx)` 入参 */
+export interface MiddlewareContextParams<C, S> {
+    app: AppInstance;
+    log: LoggerLike;
+    services: Awaited<S>;
+    holder: ConfigHolder<C>;
+}
+export declare function createMiddlewareContext<C, S>(params: MiddlewareContextParams<C, S>): MiddlewareContext<C, S>;
+/** `routers(ctx)` 入参 */
+export interface RouterContextParams<S> {
+    app: AppInstance;
+    log: LoggerLike;
+    services: Awaited<S>;
+}
+export declare function createRouterContext<S>(params: RouterContextParams<S>): RouterContext<S>;
+/** 关闭阶段视图入参 */
+export interface ShutdownContextParams<R, C, S> {
+    app: AppInstance;
+    log: LoggerLike;
+    disposer: Disposer;
+    resources: ResourcesView<R>;
+    holder: ConfigHolder<C>;
+    services: Awaited<S>;
+}
+export declare function createShutdownContext<R, C, S>(params: ShutdownContextParams<R, C, S>): ShutdownContext<R, C, S>;
+//# sourceMappingURL=context.d.ts.map

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

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

package/output/app/context.js

@@ -0,0 +1,73 @@
+import { SystemError } from './errors.js';
+/**
+ * 分阶段 ctx 的运行时构造（N1 §2）。
+ *
+ * 每个槽位拿到的是**字段最小集合**的普通对象；`config` 用 getter 暴露，出 spec 路径
+ * （`generateOpenApi` 不跑 `config` 槽位）读到它时抛 `SystemError('CONFIG_UNAVAILABLE')`
+ * —— 让「构造期不得读配置」有运行期护栏，而不仅是文档规则。
+ */
+/** 运行时镜像 `Live<T>`：剔除值为 `false` 的键（编译期静态关闭） */
+export function liveResources(resources) {
+    const result = {};
+    for (const [key, value] of Object.entries(resources)) {
+        if (value !== false) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+export function createConfigHolder() {
+    return { current: undefined };
+}
+/** 读配置：react 未就绪时抛 `SystemError('CONFIG_UNAVAILABLE')` */
+export function requireConfig(holder) {
+    if (holder.current === undefined) {
+        throw new SystemError('CONFIG_UNAVAILABLE', undefined, '配置尚未就绪（generateOpenApi 路径不跑 config 槽位）：任何单元不得在构造期读配置');
+    }
+    return holder.current;
+}
+/** 按**已知键**从配置值里取字段（框架内置单元消费配置的单一入口；不做形状校验） */
+export function readConfigKey(config, key) {
+    return config?.[key];
+}
+export function createResourcesContext(params) {
+    return { env: params.env, log: params.log };
+}
+export function createConfigContext(params) {
+    return { env: params.env, log: params.log, resources: params.resources };
+}
+export function createServiceContext(params) {
+    return {
+        log: params.log,
+        disposer: params.disposer,
+        resources: params.resources,
+        get config() {
+            return requireConfig(params.holder);
+        },
+    };
+}
+export function createMiddlewareContext(params) {
+    return {
+        app: params.app,
+        log: params.log,
+        services: params.services,
+        get config() {
+            return requireConfig(params.holder);
+        },
+    };
+}
+export function createRouterContext(params) {
+    return { app: params.app, log: params.log, services: params.services };
+}
+export function createShutdownContext(params) {
+    return {
+        app: params.app,
+        log: params.log,
+        disposer: params.disposer,
+        resources: params.resources,
+        get config() {
+            return requireConfig(params.holder);
+        },
+        services: params.services,
+    };
+}

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

@@ -0,0 +1,25 @@
+import type { ConfigEnv } from '../env.js';
+import type { FastifyInstance } from 'fastify';
+/**
+ * core `cookie`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * `@fastify/cookie`；cookie 名 / domain 从 `ctx.readConfig('server')` 取（**请求期惰性现读**，刷新后即生效）；
+ * 显式设 `sameSite`（默认 `lax`）与 `secure`（默认 `ENV === 'production'`）；注册在 `auth` 之前
+ * （框架内置序），故 `auth` 读 cookie 无需用户保证。
+ */
+export interface AuthCookieOptions {
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+}
+export interface CookieCoreOptions {
+    env: ConfigEnv;
+    /** 取最新配置中某个键的访问器（**每次调用现读**，不得缓存返回值） */
+    readConfig: (key: string) => unknown;
+}
+/** 从 `readConfig('server')` 的返回值读取 cookie 名列表（缺省 `['token']`，对齐四家现状） */
+export declare function resolveCookieNames(server: unknown): string[];
+/** 从 `readConfig('server')` 的返回值读取 cookie domain */
+export declare function resolveCookieDomain(server: unknown): string | undefined;
+export declare function registerCookie(app: FastifyInstance, options: CookieCoreOptions): void;
+//# sourceMappingURL=cookie.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../../../source/app/core/cookie.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,SAAS,CAAA;AAE5D;;;;;;GAMG;AAEH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAOD,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,SAAS,CAAA;IACd,wCAAwC;IACxC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CACrC;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAG5D;AAED,oDAAoD;AACpD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAerF"}