@homurajs/app-kit 0.0.0-stage → 26.10.13

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @homurajs/app-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+组装入口：`createApp` 渐进式装配（零注入也能跑）+ 双形态 RuntimeAdapter（qw-pages 全部未知约定的单点收口）。
+
+```ts
+import { createApp } from '@homurajs/app-kit'
+import { Hono } from 'hono'
+
+// 最小 App：零能力注入
+const { app, runtime } = 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) }] },
+  routes: myRoutes,
+})
+```
+
+固定中间件链：`basePath → request-id/日志 → /healthz（豁免守卫）→ licenseGuard → sessionMiddleware → authRoutes → App routes → 静态资源(dist/client) → SPA fallback`
+
+双形态启动：
+```ts
+import { createNodeAdapter } from '@homurajs/app-kit/serve'      // 独立：监听端口
+import { createQwPagesAdapter, exportHandlers } from '@homurajs/app-kit/qw-pages' // qw-pages：三导出对冲
+```
+
+使用示范见模板 `src/server/index.ts` 与 `src/server/qw-pages.ts`。

package/dist/adapter-BZXaYf3G.d.ts

@@ -0,0 +1,20 @@
+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 };

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+import { t as RuntimeAdapter } from "./adapter-BZXaYf3G.js";
+import { Context, Hono, MiddlewareHandler } from "hono";
+import { Logger, RuntimeInfo, RuntimeTarget, detectRuntime } from "@homurajs/core";
+//#region src/create-app.d.ts
+/** 能力实例的结构化契约（鸭子类型，避免包依赖；运行时由 App 传入） */
+interface AppDeps {
+  db?: Record<string, unknown>;
+  storage?: StorageLike;
+  sessions?: SessionManagerLike;
+  platform?: PlatformLike;
+  license?: LicenseClientLike;
+}
+/** 各能力的最小结构化契约（App 传真实例，app-kit 只透传/调用这些方法） */
+interface StorageLike {
+  uploadFile(...args: never[]): Promise<unknown>;
+}
+interface SessionManagerLike {
+  verifyAccessToken(t: string): Promise<unknown>;
+}
+interface PlatformLike {
+  name: string;
+  capabilities: readonly string[];
+}
+interface LicenseClientLike {
+  getStatus(): string;
+}
+/** auth 注入包（由 @homurajs/auth/hono 构造后传入） */
+interface AuthInject {
+  sessions: SessionManagerLike;
+  sessionMiddleware: MiddlewareHandler;
+  authRoutes: Hono;
+}
+/** license 注入包（由 @homurajs/license/hono 构造后传入） */
+interface LicenseInject {
+  client: LicenseClientLike;
+  guard: MiddlewareHandler;
+}
+interface HealthCheck {
+  name: string;
+  check: () => Promise<boolean> | boolean;
+}
+interface CreateAppOptions {
+  runtime?: RuntimeTarget | 'auto';
+  /** qw-pages 子路径挂载时，全中间件感知（默认 '/'） */
+  basePath?: string;
+  routes?: Hono | ((deps: AppDeps) => Hono);
+  /** 注入即启用认证链（sessionMiddleware + authRoutes） */
+  auth?: AuthInject | false;
+  /** 3p 注入（deps.platform 暴露给 routes，App 内 supports() 协商用能力） */
+  thirdParty?: {
+    platform: PlatformLike;
+  };
+  /** 注入即挂停服守卫 */
+  license?: LicenseInject | false;
+  /** 注入 db/storage 汇总进 deps（供 routes 回调用） */
+  db?: Record<string, unknown>;
+  storage?: StorageLike;
+  healthz?: {
+    checks?: HealthCheck[];
+  };
+  /** 静态资源目录（adapter.assetsDir() 算出）；提供则挂 static + SPA fallback */
+  staticDir?: string;
+  logger?: Logger;
+  onError?: (err: Error, c: {
+    path: string;
+  }) => Response | Promise<Response>;
+}
+interface HomuraApp {
+  app: Hono;
+  runtime: RuntimeInfo;
+}
+/**
+ * 固定中间件链（模板文档逐环解释）：
+ * basePath → requestId+访问日志 → /healthz（注册于 guard 前，天然豁免）→ licenseGuard
+ * → sessionMiddleware → authRoutes → App routes → 静态资源 → SPA fallback → onError
+ */
+export declare function createApp(options?: CreateAppOptions): HomuraApp;
+declare module 'hono' {
+  interface ContextVariableMap {
+    requestId: string;
+  }
+}
+//#endregion
+//#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

@@ -0,0 +1,176 @@
+import { Hono } from "hono";
+import { randomUUID } from "node:crypto";
+import { detectRuntime, detectRuntime as detectRuntime$1 } from "@homurajs/core";
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { extname, join, normalize, resolve, sep } from "node:path";
+import { Readable } from "node:stream";
+//#region src/static.ts
+/**
+* fs 静态资源处理 + SPA fallback（node / qw-pages 共享，均跑在 Node 上）。
+* 只做「按 path 找文件」，不监听端口——端口/导出差异归 adapter。
+*/
+const MIME = {
+	".html": "text/html; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".ico": "image/x-icon",
+	".woff": "font/woff",
+	".woff2": "font/woff2",
+	".txt": "text/plain; charset=utf-8",
+	".map": "application/json; charset=utf-8"
+};
+function mimeOf(file) {
+	return MIME[extname(file).toLowerCase()] ?? "application/octet-stream";
+}
+/** 路径穿越防护：解析后必须仍在 root 内 */
+function safeResolve(root, reqPath) {
+	const rel = decodeURIComponent(reqPath).replace(/^\/+/, "");
+	const abs = resolve(root, normalize(rel));
+	const rootWithSep = root.endsWith(sep) ? root : root + sep;
+	if (abs !== root && !abs.startsWith(rootWithSep)) return null;
+	return abs;
+}
+/** 静态文件中间件：命中则回文件，未命中 next()（交给 SPA fallback） */
+function createStaticMiddleware(root) {
+	return async (c, next) => {
+		if (c.req.method !== "GET" && c.req.method !== "HEAD") {
+			await next();
+			return;
+		}
+		const urlPath = new URL(c.req.url).pathname;
+		const abs = safeResolve(root, urlPath);
+		if (!abs || !existsSync(abs) || !statSync(abs).isFile()) {
+			await next();
+			return;
+		}
+		const isAsset = urlPath.startsWith("/assets/") || urlPath.includes(".");
+		c.header("content-type", mimeOf(abs));
+		c.header("cache-control", isAsset ? "public, max-age=31536000, immutable" : "no-cache");
+		if (c.req.method === "HEAD") return c.body(null);
+		const stream = Readable.toWeb(createReadStream(abs));
+		return c.body(stream);
+	};
+}
+/**
+* SPA fallback（notFound 处理器）：
+* - API/鉴权/文件路径 → 404 JSON
+* - 其余 GET（页面请求）→ index.html（前端路由接管）
+*/
+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({
+			error: "not_found",
+			path
+		}, 404);
+		const index = join(root, "index.html");
+		if (!existsSync(index)) return c.text("not found", 404);
+		c.header("content-type", "text/html; charset=utf-8");
+		c.header("cache-control", "no-cache");
+		const stream = Readable.toWeb(createReadStream(index));
+		return c.body(stream);
+	};
+}
+//#endregion
+//#region src/create-app.ts
+/**
+* createApp：渐进式组装入口。零注入也能跑（纯 routes），
+* 每注入一个模块解锁一层能力（auth/3p/license/db/storage 实例由 App 构造后传入）。
+* app-kit 不硬依赖这些能力包——类型采用结构化契约（鸭子类型），见 AppDeps。
+*/
+/**
+* 固定中间件链（模板文档逐环解释）：
+* basePath → requestId+访问日志 → /healthz（注册于 guard 前，天然豁免）→ licenseGuard
+* → sessionMiddleware → authRoutes → App routes → 静态资源 → SPA fallback → onError
+*/
+function createApp(options = {}) {
+	const runtime = options.runtime && options.runtime !== "auto" ? {
+		target: options.runtime,
+		explicit: true,
+		reasons: [`createApp runtime=${options.runtime}`]
+	} : detectRuntime$1(process.env);
+	const basePath = options.basePath && options.basePath !== "/" ? options.basePath : void 0;
+	const app = basePath ? new Hono().basePath(basePath) : new Hono();
+	const deps = {};
+	if (options.db) deps.db = options.db;
+	if (options.storage) deps.storage = options.storage;
+	if (options.auth) deps.sessions = options.auth.sessions;
+	if (options.thirdParty) deps.platform = options.thirdParty.platform;
+	if (options.license) deps.license = options.license.client;
+	app.use("*", async (c, next) => {
+		const reqId = c.req.header("x-request-id") ?? randomUUID();
+		c.set("requestId", reqId);
+		c.header("X-Request-Id", reqId);
+		const start = Date.now();
+		await next();
+		options.logger?.info("request", {
+			requestId: reqId,
+			method: c.req.method,
+			path: new URL(c.req.url).pathname,
+			status: c.res.status,
+			durationMs: Date.now() - start
+		});
+	});
+	const checks = options.healthz?.checks ?? [];
+	app.get("/healthz", async (c) => {
+		if (checks.length === 0) return c.json({
+			status: "ok",
+			runtime: runtime.target
+		});
+		const results = {};
+		let allOk = true;
+		for (const { name, check } of checks) try {
+			const ok = await check();
+			results[name] = ok ? "ok" : "fail";
+			if (!ok) allOk = false;
+		} catch {
+			results[name] = "fail";
+			allOk = false;
+		}
+		return c.json({
+			status: allOk ? "ok" : "degraded",
+			runtime: runtime.target,
+			checks: results
+		}, allOk ? 200 : 503);
+	});
+	if (options.license) app.use("*", options.license.guard);
+	if (options.auth) app.use("*", options.auth.sessionMiddleware);
+	if (options.auth) app.route("/", options.auth.authRoutes);
+	if (options.routes) {
+		const businessRoutes = typeof options.routes === "function" ? options.routes(deps) : options.routes;
+		app.route("/", businessRoutes);
+	}
+	if (options.staticDir) {
+		app.use("*", createStaticMiddleware(options.staticDir));
+		app.notFound(createSpaFallback(options.staticDir));
+	} else app.notFound((c) => c.json({
+		error: "not_found",
+		path: new URL(c.req.url).pathname
+	}, 404));
+	app.onError((err, c) => {
+		options.logger?.error("unhandled", {
+			err: err.message,
+			path: c.req.path,
+			requestId: c.get("requestId")
+		});
+		if (options.onError) return Promise.resolve(options.onError(err, { path: c.req.path }));
+		return c.json({
+			error: "internal_error",
+			message: err.message
+		}, 500);
+	});
+	return {
+		app,
+		runtime
+	};
+}
+//#endregion
+export { createApp, createSpaFallback, createStaticMiddleware, detectRuntime };

package/dist/qw-pages.d.ts

@@ -0,0 +1,13 @@
+import { t as RuntimeAdapter } from "./adapter-BZXaYf3G.js";
+import { Hono } from "hono";
+//#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;
+}
+export declare function createQwPagesAdapter(): RuntimeAdapter;
+/** 三重导出对冲：default / fetch / app 同时给，覆盖 qw-pages 未知入口约定 */
+export declare function exportHandlers(app: Hono): ExportHandlers;
+//#endregion

package/dist/qw-pages.js

@@ -0,0 +1,34 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+//#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 覆盖）。
+*/
+function createQwPagesAdapter() {
+	return {
+		target: "qw-pages",
+		async start() {
+			throw new Error("qw-pages 形态不监听端口：请用 exportHandlers(app) 导出 default/fetch/app，由平台调用");
+		},
+		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
+	};
+}
+//#endregion
+export { createQwPagesAdapter, exportHandlers };

package/dist/serve.d.ts

@@ -0,0 +1,4 @@
+import { t as RuntimeAdapter } from "./adapter-BZXaYf3G.js";
+//#region src/runtime/node.d.ts
+export declare function createNodeAdapter(): RuntimeAdapter;
+//#endregion

package/dist/serve.js

@@ -0,0 +1,29 @@
+import { resolve } from "node:path";
+//#region src/runtime/node.ts
+/**
+* standalone 适配器：@hono/node-server 端口监听。
+* 可选 peer：@hono/node-server（动态 import，不装也能 typecheck 其余部分）。
+* 静态资源由 createApp 的 staticDir 挂载（见 static.ts），adapter 只负责监听与 trust proxy。
+*/
+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());
+			});
+		},
+		trustProxy: () => process.env.TRUST_PROXY === "1",
+		assetsDir: (env) => resolve(env.HOMURA_ASSETS_DIR ?? "dist/client")
+	};
+}
+//#endregion
+export { createNodeAdapter };

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@homurajs/app-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "26.10.13",
+  "type": "module",
+  "description": "homura 组装入口：createApp 中间件链装配 + 双形态 RuntimeAdapter（standalone / qw-pages）",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./serve": {
+      "types": "./dist/serve.d.ts",
+      "import": "./dist/serve.js"
+    },
+    "./qw-pages": {
+      "types": "./dist/qw-pages.d.ts",
+      "import": "./dist/qw-pages.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@homurajs/core": "26.10.13",
+    "hono": "^4.10.0"
+  },
+  "peerDependencies": {
+    "@hono/node-server": "^1.19.0"
+  },
+  "peerDependenciesMeta": {
+    "@hono/node-server": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@hono/node-server": "^1.19.0",
+    "tsdown": "^0.23.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }