@taicode/common-server 4.0.0-beta.2 → 4.0.0-beta.4

package/output/{app/redis.js → redis/index.js}

@@ -1,21 +1,23 @@
-import { createRedisClient, RedisCache } from '../redis-cache/index.js';
+import { createRedisClient, RedisCache } from './cache.js';
 /**
  * 引导期 Redis / cache helper（N2 §2.13）。
  *
- * 在 `resources(ctx)` 槽位里按需调用（框架自己**不**创建 Redis）：
+ * 在 `resources(ctx)` 槽位里按需调用（框架自己**不**创建 Redis）；释放**在创建处**登记：
  *
  * ```ts
  * resources: (ctx) => {
  *   const redis = createRedis(ctx.env, ctx.log)          // 无 REDIS_URL → undefined
+ *   if (redis) {
+ *     ctx.disposer.add(() => redis.dispose())            // 关闭时 resources 阶段最后 flush
+ *   }
  *   return { redis, cache: createCache({ env: ctx.env, prefix: 'account', redis }) }
  * }
  * ```
  *
  * `REDIS_URL` 由 helper 直接读 `env`（固定约定），**不**取自 `config`；`redis` / `cache` 一律是
  * **惰性包装**：构造时不建连、不 ping，首次真正使用才建连 —— 「出 spec 不连库/Redis」结构性成立。
+ * 释放永远走调用方在 `ctx.disposer` 里的登记，框架不替资源持有句柄。
  */
-/** 一级/二级缓存默认 TTL（秒），与 `RedisCache` 默认一致 */
-export const DEFAULT_REDIS_CACHE_TTL_SECONDS = 300;
 /**
  * 构造 Redis 句柄（惰性包装：不建连、不 ping）。
  *
@@ -36,7 +38,13 @@ export function createRedis(env, log) {
                 await client.quit().catch(() => undefined);
             }
             else {
-                client.destroy();
+                // 未建连（从未使用过）时 `destroy()` 会抛 "The client is closed"；释放必须是幂等的
+                try {
+                    client.destroy();
+                }
+                catch {
+                    // 已关闭：无事可做
+                }
             }
         },
     };
@@ -59,3 +67,5 @@ export function createCache(params) {
     params.log?.debug({}, '[redis] REDIS_URL not configured; cache falls back to in-process L1');
     return new RedisCache({ prefix: params.prefix });
 }
+// ── 缓存 / 客户端实现（与引导期 helper 同一模块）───────────────
+export { RedisCache, createRedisClient } from './cache.js';

package/output/redis/index.test.d.ts

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

package/output/{context → redis}/index.test.d.ts.map

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

package/output/redis/index.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { RedisCache } from './cache.js';
+import { createCache, createRedis } from './index.js';
+function createRecordingLogger() {
+    const entries = [];
+    const record = (level) => (obj, msg) => {
+        entries.push({ level, obj, msg });
+    };
+    return { entries, debug: record('debug'), info: record('info'), warn: record('warn'), error: record('error') };
+}
+/** 测试用 `ConfigEnv`（固定读取约定：`ENV` / `API_PORT` / `LOG_LEVEL` / `DATABASE_URL` / `REDIS_URL`） */
+function createTestConfigEnv(overrides = {}) {
+    return { ENV: 'test', API_PORT: '', LOG_LEVEL: 'info', DATABASE_URL: '', REDIS_URL: undefined, ...overrides };
+}
+describe('createRedis', () => {
+    it('无 REDIS_URL → undefined，并留一条 debug 线索', () => {
+        const log = createRecordingLogger();
+        const handle = createRedis(createTestConfigEnv({ REDIS_URL: undefined }), log);
+        expect(handle).toBeUndefined();
+        expect(log.entries.filter((entry) => entry.level === 'debug')).toHaveLength(1);
+    });
+    it('有 REDIS_URL → 句柄（client + dispose），构造期不建连', () => {
+        const handle = createRedis(createTestConfigEnv({ REDIS_URL: 'redis://127.0.0.1:6379/0' }));
+        expect(handle).toBeDefined();
+        expect(handle?.client).toBeDefined();
+        expect(typeof handle?.dispose).toBe('function');
+        // 惰性：尚未 connect，客户端未打开
+        expect((handle?.client).isOpen).toBe(false);
+    });
+    it('dispose：未建连时直接销毁客户端，不抛错、可重复调用', async () => {
+        const handle = createRedis(createTestConfigEnv({ REDIS_URL: 'redis://127.0.0.1:6379/0' }));
+        await expect(handle?.dispose()).resolves.toBeUndefined();
+        await expect(handle?.dispose()).resolves.toBeUndefined();
+    });
+});
+describe('createCache', () => {
+    it('无 redis 句柄、无 REDIS_URL → 纯进程内 L1（不建连）', () => {
+        const log = createRecordingLogger();
+        const cache = createCache({ env: createTestConfigEnv({ REDIS_URL: undefined }), prefix: 'test:', log });
+        expect(cache).toBeInstanceOf(RedisCache);
+        expect(log.entries.filter((entry) => entry.level === 'debug')).toHaveLength(1);
+    });
+    it('复用传入的 redis 句柄（一条连接同时给 cache 与其它消费者）', () => {
+        const handle = createRedis(createTestConfigEnv({ REDIS_URL: 'redis://127.0.0.1:6379/0' }));
+        const cache = createCache({ env: createTestConfigEnv(), prefix: 'test:', redis: handle });
+        expect(cache).toBeInstanceOf(RedisCache);
+    });
+    it('无句柄但有 REDIS_URL → 自建客户端（由 RedisCache 自己持有）', () => {
+        const cache = createCache({
+            env: createTestConfigEnv({ REDIS_URL: 'redis://127.0.0.1:6379/0' }),
+            prefix: 'test:',
+        });
+        expect(cache).toBeInstanceOf(RedisCache);
+    });
+});

package/output/redis-queue/index.js

@@ -2,5 +2,5 @@
 export { RedisQueueProvider } from './redis-queue-provider.js';
 export { RedisQueueConsumer } from './redis-queue-consumer.js';
 export { RedisQueueBatchConsumer } from './redis-queue-batch-consumer.js';
-// 测试辅助函数导出
+// 测试辅助函数导出（与队列实现同一出口：谁提供的功能，谁提供配套的测试工具）
 export * as test from './test-helpers.js';

package/output/redis-queue/test-helpers.d.ts

@@ -14,7 +14,7 @@ import type { AnyRegistry, QueueStats, RedisQueueRegistry, Task } from './types.
  *
  * @example
  * ```ts
- * import { dispatchQueueTask } from '@taicode/common-server/redis-queue/test-helpers'
+ * import { dispatchQueueTask } from '@taicode/common-server/redis-queue'
  * import { RedisQueueProvider, RedisQueueConsumer } from '@taicode/common-server/redis-queue'
  *
  * describe('My Queue Tests', () => {

package/output/redis-queue/test-helpers.js

@@ -11,7 +11,7 @@ import { RedisQueueConsumer } from './redis-queue-consumer.js';
  *
  * @example
  * ```ts
- * import { dispatchQueueTask } from '@taicode/common-server/redis-queue/test-helpers'
+ * import { dispatchQueueTask } from '@taicode/common-server/redis-queue'
  * import { RedisQueueProvider, RedisQueueConsumer } from '@taicode/common-server/redis-queue'
  *
  * describe('My Queue Tests', () => {

package/output/redis-queue/types.d.ts

@@ -109,24 +109,18 @@ export interface RedisQueueCommonConfig {
 /**
  * 队列生产者配置
  */
-export interface RedisQueueProviderConfig {
-    redisUrl?: string;
-    redisClient?: RedisClientType;
-    cleanupDelay?: number;
+export interface RedisQueueProviderConfig extends RedisQueueCommonConfig {
     processingDelay?: number;
 }
 /**
  * 队列消费者配置
  */
-export interface RedisQueueConsumerConfig<T extends TaskData = TaskData> {
-    redisUrl?: string;
-    redisClient?: RedisClientType;
+export interface RedisQueueConsumerConfig<T extends TaskData = TaskData> extends RedisQueueCommonConfig {
     handler: TaskHandler<T>;
     maxRetries?: number;
     concurrency?: number;
     consumerInterval?: number;
     processingTimeout?: number;
-    cleanupDelay?: number;
 }
 /**
  * 任务处理器函数
@@ -135,14 +129,11 @@ export type TaskHandler<T extends TaskData = TaskData> = (data: T) => Promise<Ca
 /**
  * 批量消费者配置
  */
-export interface BatchConsumerConfig<T extends TaskData = TaskData> {
-    redisUrl?: string;
-    redisClient?: RedisClientType;
+export interface BatchConsumerConfig<T extends TaskData = TaskData> extends RedisQueueCommonConfig {
     handler: BatchTaskHandler<T>;
     batchSize?: number;
     maxRetries?: number;
     concurrency?: number;
-    cleanupDelay?: number;
     consumerInterval?: number;
     processingTimeout?: number;
 }

package/output/redis-queue/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../source/redis-queue/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../source/redis-queue/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,OAAO,CAAA;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,MAAM,WAAW,kBAAkB;CAElC;AAED;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAA;AAEtE;;;;;GAKG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAE7C;;GAEG;AAEH,MAAM,MAAM,QAAQ,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,CAAA;AAE1D;;GAEG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC,GAAG,QAAQ;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,CAAC,CAAA;IACP,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,eAAe,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,sBAAsB;IACtE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,CAAE,SAAQ,sBAAsB;IACrG,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;AAE3G;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,CAAE,SAAQ,sBAAsB;IAChG,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAA;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taicode/common-server",
-  "version": "4.0.0-beta.2",
+  "version": "4.0.0-beta.4",
   "author": "Alain",
   "license": "ISC",
   "description": "",
@@ -20,6 +20,15 @@
       "default": "./output/*/index.js"
     }
   },
+  "scripts": {
+    "test": "vitest run",
+    "test:ci": "vitest run",
+    "lint": "eslint && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf output && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "dev": "tsc -p tsconfig.json --watch"
+  },
   "files": [
     "output"
   ],
@@ -27,18 +36,19 @@
     "@fastify/cookie": "^11",
     "@fastify/cors": "^11",
     "@fastify/swagger": "^9",
-    "@scalar/fastify-api-reference": "^1",
+    "@taicode/auth-sdk": "^1.0.9",
     "dotenv": "^17.3.1",
     "fastify-type-provider-zod": "^6",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
+    "@taicode/common-base": "workspace:^",
     "fastify": "^5.5.0",
-    "redis": "^5.11.0",
-    "@taicode/common-base": "^4.0.0-beta.2"
+    "redis": "^5.11.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.3",
+    "@taicode/common-base": "workspace:^",
     "@types/node": "^22.19.13",
     "@yinxulai/eslint-plugin-peculiar": "^1.0.6",
     "eslint": "^9.39.3",
@@ -48,15 +58,6 @@
     "globals": "^16.5.0",
     "redis": "^5.11.0",
     "typescript-eslint": "^8.56.1",
-    "vitest": "^3.2.4",
-    "@taicode/common-base": "^4.0.0-beta.2"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "test:ci": "vitest run",
-    "lint": "eslint && tsc --noEmit",
-    "typecheck": "tsc --noEmit",
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch"
+    "vitest": "^3.2.4"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 TaicodeLabs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

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

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

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

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

package/output/app/auth.test.js

@@ -1,148 +0,0 @@
-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

@@ -1,39 +0,0 @@
-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>;
-}
-/**
- * 装配一个服务（`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

@@ -1 +0,0 @@
-{"version":3,"file":"boot.d.ts","sourceRoot":"","sources":["../../source/app/boot.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AACtG,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;AAqCD;;;;;;;;;;;;;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,CA6GhG"}

package/output/app/boot.js

@@ -1,140 +0,0 @@
-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;
-}
-/**
- * 把各资源通过 `ctx.registerClassifyError` 注册的错误分类器合成单个分类器。
- *
- * 范式：**一个资源一个分类器，各管各的错误域**（认领不了就返回 `null` 交给下一个）。
- *
- * - 零个 → `undefined`（响应层落 `UNKNOWN_ERROR` 兜底）；
- * - 一个 → 原样返回（少一层包装）；
- * - 多个 → 按**注册顺序**串成链，返回第一个非 `null` 的结果（短路）。
- */
-function combineClassifiers(classifiers) {
-    if (classifiers.length === 0) {
-        return undefined;
-    }
-    if (classifiers.length === 1) {
-        return classifiers[0];
-    }
-    return (error) => {
-        for (const classifier of classifiers) {
-            const result = classifier(error);
-            if (result !== null) {
-                return result;
-            }
-        }
-        return null;
-    };
-}
-/**
- * 装配一个服务（`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 路径同样执行）
-    //    资源错误分类器由各资源通过 `ctx.registerClassifyError` 各自注册：在调 `resources(ctx)` 前建局部收集器，
-    //    返回后把注册结果按注册顺序合成单个分类器喂给 core。
-    const classifiers = [];
-    const resources = (await server.resources(createResourcesContext({
-        env,
-        log,
-        registerClassifyError: (classifier) => {
-            classifiers.push(classifier);
-        },
-    })));
-    const resourcesView = liveResources(resources);
-    // ③ core 装配（schema → cookie → response → openapi → 路由注册表）
-    await registerCore(app, {
-        identity: server.app,
-        env,
-        classifyResourceError: combineClassifiers(classifiers),
-        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

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

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

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