@homurajs/app-kit 26.10.13 → 26.10.14

package/README.md

@@ -1,30 +1,43 @@
 # @homurajs/app-kit
 
-组装入口：`createApp` 渐进式装配（零注入也能跑）+ 双形态 RuntimeAdapter（qw-pages 全部未知约定的单点收口）。
+组装入口：`createApp` 渐进式装配（零注入也能跑）+ 双形态 RuntimeAdapter（跨形态差异的单点收口）。
 
 ```ts
 import { createApp } from '@homurajs/app-kit'
 import { Hono } from 'hono'
 
 // 最小 App：零能力注入
-const { app, runtime } = createApp({ routes: (deps) => myRoutes(deps) })
+const { app, runtime, healthzPath } = createApp({ routes: (deps) => myRoutes(deps) })
 
 // 渐进解锁：注入即启用（实例由 App 构造，app-kit 不硬依赖能力包）
 const composed = createApp({
-  auth: { sessions, sessionMiddleware, authRoutes },   // 登录链
-  license: { client: license, guard: licenseGuard },    // 激活守卫
-  thirdParty: { platform },                             // deps.platform 暴露给路由
-  healthz: { checks: [{ name: 'db', check: () => db.select().from(...).limit(1).then(() => true) }] },
+  auth: { sessions, sessionMiddleware, authRoutes }, // 登录链
+  license: { client: license, guard: licenseGuard }, // 激活守卫
+  thirdParty: { platform }, // deps.platform 暴露给路由
+  healthz: { checks: [{ name: 'db', check: () => pingDb() }] },
   routes: myRoutes,
 })
 ```
 
-固定中间件链：`basePath → request-id/日志 → /healthz（豁免守卫）→ licenseGuard → sessionMiddleware → authRoutes → App routes → 静态资源(dist/client) → SPA fallback`
+固定中间件链：`basePath → request-id/日志 → healthz（豁免守卫，路径按形态取）→ licenseGuard → sessionMiddleware → authRoutes → App routes → 静态资源 → SPA fallback`
+
+**健康检查路径按形态取**（`healthz.path` 可覆盖，缺省来自 `@homurajs/core` 的 `healthzPathFor`）：
+standalone 用 `/healthz`；qw-pages 用 `/_healthz`——因为 `/healthz` 被平台 Page Gateway 保留，
+网关自答 `ok` 且请求**不下发到 App 进程**（2026-10-13 实测）。若你自定义了路径，
+`@homurajs/license` 的守卫豁免清单要传同一个值：`licenseGuard(client, { healthzPath })`。
+
+双形态启动（**两者都监听端口**，差异只在缺省值）：
 
-双形态启动：
 ```ts
-import { createNodeAdapter } from '@homurajs/app-kit/serve'      // 独立：监听端口
-import { createQwPagesAdapter, exportHandlers } from '@homurajs/app-kit/qw-pages' // qw-pages：三导出对冲
+import { createNodeAdapter } from '@homurajs/app-kit/serve' // 独立：PORT ?? 3000，assetsDir=dist/client
+import { createQwPagesAdapter } from '@homurajs/app-kit/qw-pages' // qw-pages：PORT ?? 8081 + HOST，assetsDir=client
 ```
 
+> qw-pages 动态页 = 平台拉起 `node <entrypoint>` 的常驻进程，注入 `PORT`/`HOST` 并把网关流量反代到该 socket。
+> **不存在** `default`/`fetch`/`app` 之类的 serverless 导出约定（实测：导出函数命中 0 次），
+> 旧版的 `exportHandlers` 三重对冲已删除。详见仓库 `docs/specs/module-qw-pages.md`。
+
+`trustProxy()` 的用途：qw-pages 恒为 true（网关后、公网 https），standalone 由 `TRUST_PROXY=1` 开启。
+把它接到 `@homurajs/auth` 的 cookie `secure` 选项上，否则 https 站点会发非 Secure cookie。
+
 使用示范见模板 `src/server/index.ts` 与 `src/server/qw-pages.ts`。

package/dist/adapter-CAQkfPMf.d.ts

@@ -0,0 +1,28 @@
+import { Hono } from "hono";
+import { RuntimeTarget } from "@homurajs/core";
+//#region src/runtime/adapter.d.ts
+/**
+ * 双形态运行时适配器——跨形态差异的单点收口。
+ * 差异项（监听端口/HOST 缺省、trust proxy、静态资源目录）全走 adapter，业务代码零 if-else。
+ *
+ * 注：qw-pages 的约定已于 2026-10-13 全部实测确认（见 runtime/qw-pages.ts 头部与
+ * docs/specs/module-qw-pages.md），本接口不再是「对冲未知」，而是两形态真实差异的最小面。
+ * 两个适配器都监听端口——平台形态差异只剩默认值，不存在「平台调用导出函数」的形态。
+ */
+interface RuntimeAdapter {
+  target: RuntimeTarget;
+  start(app: Hono, opts: {
+    port?: number;
+    signal?: AbortSignal;
+  }): Promise<void>;
+  /**
+   * 是否在反向代理后（决定 cookie secure 与 X-Forwarded-* 可信度）。
+   * qw-pages 恒为 true；standalone 由 TRUST_PROXY=1 开启。
+   * 消费方：模板把它接到 @homurajs/auth 的 `secure` 选项上。
+   */
+  trustProxy(): boolean;
+  /** 静态资源目录：standalone 默认 dist/client，qw-pages 默认 client；均可被 HOMURA_ASSETS_DIR 覆盖 */
+  assetsDir(env: NodeJS.ProcessEnv): string;
+}
+//#endregion
+export { RuntimeAdapter as t };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { t as RuntimeAdapter } from "./adapter-BZXaYf3G.js";
+import { t as RuntimeAdapter } from "./adapter-CAQkfPMf.js";
 import { Context, Hono, MiddlewareHandler } from "hono";
 import { Logger, RuntimeInfo, RuntimeTarget, detectRuntime } from "@homurajs/core";
 //#region src/create-app.d.ts
@@ -55,7 +55,13 @@ interface CreateAppOptions {
   /** 注入 db/storage 汇总进 deps（供 routes 回调用） */
   db?: Record<string, unknown>;
   storage?: StorageLike;
+  /**
+   * 健康检查：路径缺省按形态取 core healthzPathFor(target)——
+   * qw-pages 上 '/healthz' 被 Page Gateway 保留（网关自答，请求不下发到 App），故用 '/_healthz'。
+   * 显式传 path 时，license guard 的豁免清单必须用同一个值（见 license createDefaultBypass）。
+   */
   healthz?: {
+    path?: string;
     checks?: HealthCheck[];
   };
   /** 静态资源目录（adapter.assetsDir() 算出）；提供则挂 static + SPA fallback */
@@ -68,10 +74,12 @@ interface CreateAppOptions {
 interface HomuraApp {
   app: Hono;
   runtime: RuntimeInfo;
+  /** 实际注册的健康检查路径（供 license guard 豁免清单等同源消费） */
+  healthzPath: string;
 }
 /**
  * 固定中间件链（模板文档逐环解释）：
- * basePath → requestId+访问日志 → /healthz（注册于 guard 前，天然豁免）→ licenseGuard
+ * basePath → requestId+访问日志 → healthz（注册于 guard 前，天然豁免；路径按形态取）→ licenseGuard
  * → sessionMiddleware → authRoutes → App routes → 静态资源 → SPA fallback → onError
  */
 export declare function createApp(options?: CreateAppOptions): HomuraApp;
@@ -84,11 +92,6 @@ declare module 'hono' {
 //#region src/static.d.ts
 /** 静态文件中间件：命中则回文件，未命中 next()（交给 SPA fallback） */
 export declare function createStaticMiddleware(root: string): MiddlewareHandler;
-/**
- * SPA fallback（notFound 处理器）：
- * - API/鉴权/文件路径 → 404 JSON
- * - 其余 GET（页面请求）→ index.html（前端路由接管）
- */
 export declare function createSpaFallback(root: string): (c: Context) => Response | Promise<Response>;
 //#endregion
 export { type AppDeps, type AuthInject, type CreateAppOptions, type HealthCheck, type HomuraApp, type LicenseClientLike, type LicenseInject, type PlatformLike, type RuntimeAdapter, type SessionManagerLike, type StorageLike, detectRuntime };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import { randomUUID } from "node:crypto";
-import { detectRuntime, detectRuntime as detectRuntime$1 } from "@homurajs/core";
+import { HEALTHZ_PATH, detectRuntime, detectRuntime as detectRuntime$1, healthzPathFor } from "@homurajs/core";
 import { createReadStream, existsSync, statSync } from "node:fs";
 import { extname, join, normalize, resolve, sep } from "node:path";
 import { Readable } from "node:stream";
@@ -30,9 +30,15 @@ const MIME = {
 function mimeOf(file) {
 	return MIME[extname(file).toLowerCase()] ?? "application/octet-stream";
 }
-/** 路径穿越防护：解析后必须仍在 root 内 */
+/** 路径穿越防护：解析后必须仍在 root 内；畸形百分号编码返回 null（404），不抛（避免 500） */
 function safeResolve(root, reqPath) {
-	const rel = decodeURIComponent(reqPath).replace(/^\/+/, "");
+	let decoded;
+	try {
+		decoded = decodeURIComponent(reqPath);
+	} catch {
+		return null;
+	}
+	const rel = decoded.replace(/^\/+/, "");
 	const abs = resolve(root, normalize(rel));
 	const rootWithSep = root.endsWith(sep) ? root : root + sep;
 	if (abs !== root && !abs.startsWith(rootWithSep)) return null;
@@ -61,13 +67,23 @@ function createStaticMiddleware(root) {
 }
 /**
 * SPA fallback（notFound 处理器）：
-* - API/鉴权/文件路径 → 404 JSON
+* - API/鉴权/文件/健康检查路径 → 404 JSON
 * - 其余 GET（页面请求）→ index.html（前端路由接管）
+*
+* 保留前缀含两形态的健康检查路径（core HEALTHZ_PATH 同源）：qw-pages 用 '/_healthz'，
+* standalone 用 '/healthz'，两个都列入，避免路径改名后 fallback 把健康检查当页面请求。
 */
+const RESERVED_PREFIXES = [
+	"/api",
+	"/auth",
+	"/files",
+	HEALTHZ_PATH.standalone,
+	HEALTHZ_PATH["qw-pages"]
+];
 function createSpaFallback(root) {
 	return async (c) => {
 		const path = new URL(c.req.url).pathname;
-		if (path.startsWith("/api") || path.startsWith("/auth") || path.startsWith("/files") || path.startsWith("/healthz") || c.req.method !== "GET") return c.json({
+		if (RESERVED_PREFIXES.some((prefix) => path.startsWith(prefix)) || c.req.method !== "GET") return c.json({
 			error: "not_found",
 			path
 		}, 404);
@@ -88,7 +104,7 @@ function createSpaFallback(root) {
 */
 /**
 * 固定中间件链（模板文档逐环解释）：
-* basePath → requestId+访问日志 → /healthz（注册于 guard 前，天然豁免）→ licenseGuard
+* basePath → requestId+访问日志 → healthz（注册于 guard 前，天然豁免；路径按形态取）→ licenseGuard
 * → sessionMiddleware → authRoutes → App routes → 静态资源 → SPA fallback → onError
 */
 function createApp(options = {}) {
@@ -119,8 +135,9 @@ function createApp(options = {}) {
 			durationMs: Date.now() - start
 		});
 	});
+	const healthzPath = options.healthz?.path ?? healthzPathFor(runtime.target);
 	const checks = options.healthz?.checks ?? [];
-	app.get("/healthz", async (c) => {
+	app.get(healthzPath, async (c) => {
 		if (checks.length === 0) return c.json({
 			status: "ok",
 			runtime: runtime.target
@@ -169,7 +186,8 @@ function createApp(options = {}) {
 	});
 	return {
 		app,
-		runtime
+		runtime,
+		healthzPath
 	};
 }
 //#endregion

package/dist/qw-pages.d.ts

@@ -1,13 +1,6 @@
-import { t as RuntimeAdapter } from "./adapter-BZXaYf3G.js";
-import { Hono } from "hono";
+import { t as RuntimeAdapter } from "./adapter-CAQkfPMf.js";
 //#region src/runtime/qw-pages.d.ts
-export interface ExportHandlers {
-  /** qw-pages 入口约定未知的三重对冲：default / fetch / app 同时导出 */
-  default: (req: Request) => Promise<Response>;
-  fetch: (req: Request) => Promise<Response>;
-  app: Hono;
-}
+/** qw-pages 推荐端口（实测平台注入 PORT=8081；9000 被平台禁用） */
+export declare const QW_PAGES_DEFAULT_PORT = 8081;
 export declare function createQwPagesAdapter(): RuntimeAdapter;
-/** 三重导出对冲：default / fetch / app 同时给，覆盖 qw-pages 未知入口约定 */
-export declare function exportHandlers(app: Hono): ExportHandlers;
 //#endregion

package/dist/qw-pages.js

@@ -1,34 +1,36 @@
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { listenWithNodeServer } from "./serve.js";
+import { resolve } from "node:path";
 //#region src/runtime/qw-pages.ts
 /**
-* qw-pages 适配器：不监听端口；exportHandlers 同时给 default/fetch/app
-* 三种导出形态（对冲 qw-pages 入口约定未知）。
-* 静态资源相对 import.meta.url 定位——自包含 bundle 下 server 产物与 client assets 同级，
-* 故从当前模块 URL 回溯到 dist/ 再进 client/（可被 HOMURA_ASSETS_DIR 覆盖）。
+* qw-pages 适配器。
+*
+* 2026-10-13 在真实 qw-pages 动态页上实测（探针 + 双路计数归因，定论见 docs/specs/module-qw-pages.md）：
+*
+* 1. **入口约定 = 常驻 Node 进程**：平台注入 PORT/HOST 并把网关流量反代到 App 自监听的 socket。
+*    探针同时挂了 serve() 与 default/fetch/app 三重导出，全程 `serve` 命中 47 次、`handler` 命中 0 次
+*    → 平台从不调用导出函数。故原 exportHandlers 三重对冲已删除，本适配器改为与 standalone 共用监听实现。
+* 2. **HOST 实测注入为 127.0.0.1**（网关与 App 同网络命名空间），故缺省绑 loopback 而非全网卡。
+* 3. **发布根目录即产物根**（实测 cwd=/opt/qwenwork-page/app），静态目录默认 `client`，
+*    不是 standalone 的 `dist/client`。不再用 import.meta.url 回溯定位：按 npm 依赖消费时
+*    该算法会落到 `node_modules/@homurajs/app-kit/client`（实测证伪，目录不存在）。
+* 4. **'/healthz' 被 Page Gateway 保留**（网关自答 `ok`，请求不下发到进程），
+*    健康检查路径统一取 core 的 healthzPathFor('qw-pages') = '/_healthz'。
+* 5. 平台对 HTML 响应做后处理（注入页面 chrome 脚本并覆盖 Cache-Control），非 HTML 资源原样透传，
+*    故 static.ts 的缓存头策略在 Pages 上仍然有效，但不要依赖 HTML 的字节长度/ETag。
 */
+/** qw-pages 推荐端口（实测平台注入 PORT=8081；9000 被平台禁用） */
+const QW_PAGES_DEFAULT_PORT = 8081;
 function createQwPagesAdapter() {
 	return {
 		target: "qw-pages",
-		async start() {
-			throw new Error("qw-pages 形态不监听端口：请用 exportHandlers(app) 导出 default/fetch/app，由平台调用");
-		},
+		start: (app, opts) => listenWithNodeServer(app, {
+			port: opts.port ?? Number(process.env.PORT ?? 8081),
+			hostname: process.env.HOST ?? "127.0.0.1",
+			signal: opts.signal
+		}),
 		trustProxy: () => true,
-		assetsDir: (env) => {
-			if (env.HOMURA_ASSETS_DIR) return resolve(env.HOMURA_ASSETS_DIR);
-			const here = dirname(fileURLToPath(import.meta.url));
-			return resolve(here, "../client");
-		}
-	};
-}
-/** 三重导出对冲：default / fetch / app 同时给，覆盖 qw-pages 未知入口约定 */
-function exportHandlers(app) {
-	const handler = (req) => Promise.resolve(app.fetch(req));
-	return {
-		default: handler,
-		fetch: handler,
-		app
+		assetsDir: (env) => resolve(env.HOMURA_ASSETS_DIR ?? "client")
 	};
 }
 //#endregion
-export { createQwPagesAdapter, exportHandlers };
+export { QW_PAGES_DEFAULT_PORT, createQwPagesAdapter };

package/dist/serve.d.ts

@@ -1,4 +1,13 @@
-import { t as RuntimeAdapter } from "./adapter-BZXaYf3G.js";
+import { t as RuntimeAdapter } from "./adapter-CAQkfPMf.js";
+import { Hono } from "hono";
 //#region src/runtime/node.d.ts
+export interface ListenOptions {
+  port?: number;
+  /** 缺省读 process.env.HOST，再缺省 0.0.0.0 */
+  hostname?: string;
+  signal?: AbortSignal;
+}
+/** 共享监听实现：读 PORT/HOST，支持 AbortSignal 优雅关闭 */
+export declare function listenWithNodeServer(app: Hono, opts?: ListenOptions): Promise<void>;
 export declare function createNodeAdapter(): RuntimeAdapter;
 //#endregion

package/dist/serve.js

@@ -4,26 +4,34 @@ import { resolve } from "node:path";
 * standalone 适配器：@hono/node-server 端口监听。
 * 可选 peer：@hono/node-server（动态 import，不装也能 typecheck 其余部分）。
 * 静态资源由 createApp 的 staticDir 挂载（见 static.ts），adapter 只负责监听与 trust proxy。
+*
+* listenWithNodeServer 同时被 qw-pages 适配器复用：2026-10-13 线上实测确认，qw-pages 动态页
+* 与 standalone 一样是「平台拉起 node <entrypoint>，网关反代到 App 自监听的 socket」，
+* 并不存在 serverless fetch-handler 入口约定，故两形态共用同一套监听实现，只差端口/HOST 默认值。
 */
+/** 共享监听实现：读 PORT/HOST，支持 AbortSignal 优雅关闭 */
+async function listenWithNodeServer(app, opts = {}) {
+	const { serve } = await import("@hono/node-server");
+	const port = opts.port ?? Number(process.env.PORT ?? 3e3);
+	const hostname = opts.hostname ?? process.env.HOST ?? "0.0.0.0";
+	return new Promise((resolveStart) => {
+		const server = serve({
+			fetch: app.fetch,
+			port,
+			hostname
+		}, () => {
+			resolveStart();
+		});
+		opts.signal?.addEventListener("abort", () => server.close());
+	});
+}
 function createNodeAdapter() {
 	return {
 		target: "standalone",
-		async start(app, opts) {
-			const { serve } = await import("@hono/node-server");
-			const port = opts.port ?? Number(process.env.PORT ?? 3e3);
-			return new Promise((resolveStart) => {
-				const server = serve({
-					fetch: app.fetch,
-					port
-				}, () => {
-					resolveStart();
-				});
-				opts.signal?.addEventListener("abort", () => server.close());
-			});
-		},
+		start: (app, opts) => listenWithNodeServer(app, opts),
 		trustProxy: () => process.env.TRUST_PROXY === "1",
 		assetsDir: (env) => resolve(env.HOMURA_ASSETS_DIR ?? "dist/client")
 	};
 }
 //#endregion
-export { createNodeAdapter };
+export { createNodeAdapter, listenWithNodeServer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homurajs/app-kit",
-  "version": "26.10.13",
+  "version": "26.10.14",
   "type": "module",
   "description": "homura 组装入口：createApp 中间件链装配 + 双形态 RuntimeAdapter（standalone / qw-pages）",
   "engines": {
@@ -28,7 +28,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@homurajs/core": "26.10.13",
+    "@homurajs/core": "26.10.14",
     "hono": "^4.10.0"
   },
   "peerDependencies": {

package/dist/adapter-BZXaYf3G.d.ts

@@ -1,20 +0,0 @@
-import { Hono } from "hono";
-import { RuntimeTarget } from "@homurajs/core";
-//#region src/runtime/adapter.d.ts
-/**
- * 双形态运行时适配器——qw-pages 全部未知约定的单点收口。
- * 跨形态差异（trust proxy、静态服务、端口）全走 adapter，业务代码零 if-else。
- */
-interface RuntimeAdapter {
-  target: RuntimeTarget;
-  start(app: Hono, opts: {
-    port?: number;
-    signal?: AbortSignal;
-  }): Promise<void>;
-  /** qw-pages 在网关后 → 信任 X-Forwarded-*（影响 cookie secure/redirect URL） */
-  trustProxy(): boolean;
-  /** 默认 dist/client，可被 HOMURA_ASSETS_DIR 覆盖 */
-  assetsDir(env: NodeJS.ProcessEnv): string;
-}
-//#endregion
-export { RuntimeAdapter as t };