@homurajs/core 26.10.13 → 26.10.14

package/README.md

@@ -1,28 +1,53 @@
 # @homurajs/core
 
-基座包（零依赖）：运行环境探测、配置装载、结构化日志、TTL-KV。
+基座包（零依赖）：运行环境探测、形态相关常量、配置装载、部署期配置文件、结构化日志、TTL-KV。
 
 ```ts
-import { detectRuntime, defineConfig, parses, createLogger, createMemoryTtlKv } from '@homurajs/core'
+import {
+  detectRuntime,
+  healthzPathFor,
+  HEALTHZ_PATH,
+  defineConfig,
+  parses,
+  applyEnvFile,
+  resolveConfigFilePath,
+  parseEnvFile,
+  createLogger,
+  createMemoryTtlKv,
+} from '@homurajs/core'
 
-// 1. 环境：HOMURA_RUNTIME 显式优先，QW_PAGES* 标记启发式
+// 1. 形态探测：HOMURA_RUNTIME 显式优先，否则按平台实测注入的标记启发式判断
 const { target } = detectRuntime(process.env) // 'standalone' | 'qw-pages'
+// qw-pages 的标记是 QWENWORK_WRITABLE_DIR / SUPABASE_INSTANCE_ID（线上实测）；
+// 平台并不注入任何 QW_PAGES* 变量，别用 HOST/PORT 当标记（standalone 也常设）
 
-// 2. 配置即文档：load() + help()（生成 .env.example 片段）
+// 2. 形态相关路径常量：app-kit 注册路由与 license guard 豁免清单必须同源读它
+healthzPathFor(target) // standalone → '/healthz'；qw-pages → '/_healthz'
+// 原因：'/healthz' 被 qw-pages 的 Page Gateway 保留，网关自答 ok 且请求不下发到 App
+
+// 3. 配置即文档：load() + help()（help 用于生成 .env.example）
 const config = defineConfig({
   port: { env: 'PORT', default: 3000, parse: parses.int, description: '监听端口' },
   secret: { env: 'APP_SECRET', parse: parses.string, required: true, secret: true },
 })
 const cfg = config.load()
 
-// 3. 日志：JSON lines、级别过滤、敏感字段打码、child scope
+// 4. 部署期配置文件：qw-pages 无自定义 env 注入口，密钥只能随产物携带
+//    优先级 HOMURA_CONFIG_FILE → <cwd>/homura.config.env → QWENWORK_WRITABLE_DIR/homura.config.env
+//    真实 env 优先于文件；必须在 defineConfig().load() 之前调用
+applyEnvFile(process.env)
+parseEnvFile('A=1\n# 注释\nexport B="x\\ny"\n') // → { A: '1', B: 'x\ny' }
+
+// 5. 日志：JSON lines、级别过滤、敏感字段打码、child scope
 const log = createLogger().child('auth')
 log.info('登录成功', { userId: 'u1' })
 
-// 4. TTL-KV：一次性消费语义（OAuth state 等）
+// 6. TTL-KV：一次性消费语义（OAuth state 等）
 const kv = createMemoryTtlKv()
 await kv.set(state, value, 5 * 60_000)
 const taken = await kv.take(state) // 取出即删；过期 null
 ```
 
-多实例部署改用 `@homurajs/db` 的 `createDbTtlKv`。使用示范见 `templates/hono-react/src/server/app.ts`（buildAuth 里 `stateKv: createMemoryTtlKv()`）。
+TTL-KV 的持久化版本在 `@homurajs/db`：SQL 形态用 `createDbTtlKv`，**qw-pages（REST 形态）用 `createRestTtlKv`**——内存版在 Pages 上进程重启即清空（跨发布必换实例），OAuth state 会断在「跳转 → 回调」两条腿之间。
+
+使用示范见 `templates/hono-react/src/server/env.ts`（`loadConfig` 里 `applyEnvFile` + `assertSecretsOverridden`）与 `app.ts`（`stateKv` 按形态选择）。

package/dist/index.d.ts

@@ -1,9 +1,15 @@
 //#region src/runtime.d.ts
 /**
- * 运行环境探测。
+ * 运行环境探测 + 形态相关的运行时常量。
  *
  * 显式配置（HOMURA_RUNTIME）永远优先；探测仅为零配置体验的缺省，
  * 标记列表集中在 QW_PAGES_ENV_MARKERS，属启发式，可被显式值覆盖。
+ *
+ * 标记来源：2026-10-13 在真实 qw-pages 动态页上实测（线上探针回读 process.env 全集）。
+ * 平台注入集只有 12 个变量：PORT / HOST / NODE_ENV / HOME / TMPDIR / XDG_* /
+ * QWENWORK_WRITABLE_DIR / SUPABASE_URL / SUPABASE_ANON_KEY / SUPABASE_INSTANCE_ID。
+ * 不存在任何 QW_PAGES* 命名的变量——旧标记 ['QW_PAGES','QW_PAGES_APP_ID'] 已证伪移除，
+ * 定论见 docs/specs/module-qw-pages.md 第 5 项。
  */
 export type RuntimeTarget = 'standalone' | 'qw-pages';
 export interface RuntimeInfo {
@@ -13,8 +19,24 @@ export interface RuntimeInfo {
   /** 探测依据（explicit=false 时给出命中的标记） */
   reasons: string[];
 }
-/** qw-pages 环境的启发式标记（文档标注：启发式、可被 HOMURA_RUNTIME 覆盖） */
+/**
+ * qw-pages 环境的启发式标记（实测注入，可被 HOMURA_RUNTIME 覆盖）。
+ * - QWENWORK_WRITABLE_DIR：平台必注入的唯一可写目录（实测 /tmp/qwenwork-page，跨发布清空）
+ * - SUPABASE_INSTANCE_ID：仅在 Page 绑定数据库后注入，故只作辅助标记
+ * 不纳入 HOST/PORT：standalone 部署也常设这两个变量，会造成误判。
+ */
 export declare const QW_PAGES_ENV_MARKERS: readonly string[];
+/**
+ * 健康检查路径按形态取值——同源常量：app-kit 注册路由、license guard 豁免清单、
+ * 模板 SPA fallback 的保留前缀都读它，避免三处各写一份而漂移。
+ *
+ * qw-pages 上 '/healthz' 被 Page Gateway 保留：实测网关自答 `ok`（text/plain），
+ * 请求不下发到 App 进程（探针 serve 计数不增），因此 App 注册在 '/healthz'
+ * 的检查项在 Pages 上永远不可达。
+ */
+export declare const HEALTHZ_PATH: Readonly<Record<RuntimeTarget, string>>;
+/** 取指定形态的健康检查路径 */
+export declare function healthzPathFor(target: RuntimeTarget): string;
 export declare function detectRuntime(env: NodeJS.ProcessEnv): RuntimeInfo;
 //#endregion
 //#region src/config.d.ts
@@ -55,6 +77,52 @@ export declare const parses: {
   readonly boolean: (raw: string) => boolean;
 };
 //#endregion
+//#region src/env-file.d.ts
+/** 配置文件名（缺省）；产物根 = 运行时 cwd，故 <cwd>/homura.config.env 即随产物携带的那份 */
+export declare const CONFIG_FILE_NAME = "homura.config.env";
+/**
+ * 解析 KEY=VALUE 行格式。
+ * - 跳过空行与 `#` 注释行；支持 `export KEY=VALUE`
+ * - 单引号：字面量，不解析转义；双引号：解析 \n \t \r \" \\ 转义
+ * - 无引号：去掉行尾 ` #...` 内联注释（前必须有空白），并 trim
+ * - 同名键后者覆盖前者
+ * - 非法行抛错并带上行号（fail fast：配置写错不该静默忽略）
+ */
+export declare function parseEnvFile(text: string): Record<string, string>;
+export interface ResolveConfigFileOptions {
+  /** 显式路径（绝对或相对 cwd）；缺省读 env.HOMURA_CONFIG_FILE */
+  path?: string;
+  cwd?: string;
+  /** 额外候选目录（缺省会追加 QWENWORK_WRITABLE_DIR，即平台唯一可写区） */
+  extraDirs?: string[];
+}
+/**
+ * 定位配置文件，按优先级返回第一个存在的：
+ * 1. 显式 path / `HOMURA_CONFIG_FILE`
+ * 2. `<cwd>/homura.config.env`（= 部署产物根，随产物携带的那份）
+ * 3. `<QWENWORK_WRITABLE_DIR>/homura.config.env`（平台可写区：可在不改产物的情况下投放/轮换）
+ * 4. extraDirs 下的同名文件
+ * 都不存在返回 null（零配置也能跑——渐进式）。
+ */
+export declare function resolveConfigFilePath(env: NodeJS.ProcessEnv, opts?: ResolveConfigFileOptions): string | null;
+export interface ApplyEnvFileOptions extends ResolveConfigFileOptions {
+  /** true 时文件值覆盖已有 env（缺省 false：真实 env 优先） */
+  override?: boolean;
+}
+export interface ApplyEnvFileResult {
+  /** 实际使用的文件路径；null = 没有配置文件（零配置运行） */
+  path: string | null;
+  /** 写入 env 的变量名 */
+  applied: string[];
+  /** 因已有真实 env 而跳过的变量名 */
+  skipped: string[];
+}
+/**
+ * 把配置文件并入 env（就地修改传入对象，通常就是 process.env）。
+ * 必须在 defineConfig(...).load(env) **之前**调用。
+ */
+export declare function applyEnvFile(env: NodeJS.ProcessEnv, opts?: ApplyEnvFileOptions): ApplyEnvFileResult;
+//#endregion
 //#region src/logger.d.ts
 /**
  * 结构化日志（轻量零依赖实现）：JSON lines 输出，便于 qw-pages 等平台收集。

package/dist/index.js

@@ -1,7 +1,30 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 import { randomBytes } from "node:crypto";
 //#region src/runtime.ts
-/** qw-pages 环境的启发式标记（文档标注：启发式、可被 HOMURA_RUNTIME 覆盖） */
-const QW_PAGES_ENV_MARKERS = ["QW_PAGES", "QW_PAGES_APP_ID"];
+/**
+* qw-pages 环境的启发式标记（实测注入，可被 HOMURA_RUNTIME 覆盖）。
+* - QWENWORK_WRITABLE_DIR：平台必注入的唯一可写目录（实测 /tmp/qwenwork-page，跨发布清空）
+* - SUPABASE_INSTANCE_ID：仅在 Page 绑定数据库后注入，故只作辅助标记
+* 不纳入 HOST/PORT：standalone 部署也常设这两个变量，会造成误判。
+*/
+const QW_PAGES_ENV_MARKERS = ["QWENWORK_WRITABLE_DIR", "SUPABASE_INSTANCE_ID"];
+/**
+* 健康检查路径按形态取值——同源常量：app-kit 注册路由、license guard 豁免清单、
+* 模板 SPA fallback 的保留前缀都读它，避免三处各写一份而漂移。
+*
+* qw-pages 上 '/healthz' 被 Page Gateway 保留：实测网关自答 `ok`（text/plain），
+* 请求不下发到 App 进程（探针 serve 计数不增），因此 App 注册在 '/healthz'
+* 的检查项在 Pages 上永远不可达。
+*/
+const HEALTHZ_PATH = {
+	standalone: "/healthz",
+	"qw-pages": "/_healthz"
+};
+/** 取指定形态的健康检查路径 */
+function healthzPathFor(target) {
+	return HEALTHZ_PATH[target];
+}
 function detectRuntime(env) {
 	const explicit = env["HOMURA_RUNTIME"];
 	if (explicit !== void 0) {
@@ -79,6 +102,105 @@ const parses = {
 	boolean: (raw) => raw === "1" || raw.toLowerCase() === "true"
 };
 //#endregion
+//#region src/env-file.ts
+/**
+* 部署期配置文件加载（KEY=VALUE 行格式，dotenv 语义子集，零依赖）。
+*
+* 为什么需要它：qw-pages 平台只注入固定 12 个 env，且**没有自定义 env/secret 注入口**
+* （实测），故 SESSION_SECRET / OAUTH_CLIENT_SECRET 这类值无法用环境变量投递。
+* 而部署产物本身不可被公网读取（实测：请求 /server/*.mjs、/homura.manifest.json 一律被
+* SPA fallback 兜成 index.html，%2e%2e 变体被网关 400，而真实 /assets/*.js 正常返回），
+* 所以「随产物携带一个配置文件」是可行的投递通道，其信任边界与代码本身相同。
+*
+* 为什么是 env 行格式而不是 yaml/json：整个配置面已经是 env 形状（configSpecs +
+* defineConfig），把文件内容并进 process.env 后能力包零改动，也不需要引解析器。
+* 需要 yaml 时再加一个 source 适配即可，属加法而非改造。
+*
+* 优先级：**真实 env > 文件**（override=false，缺省）。standalone 仍可用环境变量覆盖，
+* 与 12-factor 习惯一致；也便于本地调试时临时改一个值而不编辑文件。
+*/
+const KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** 配置文件名（缺省）；产物根 = 运行时 cwd，故 <cwd>/homura.config.env 即随产物携带的那份 */
+const CONFIG_FILE_NAME = "homura.config.env";
+/**
+* 解析 KEY=VALUE 行格式。
+* - 跳过空行与 `#` 注释行；支持 `export KEY=VALUE`
+* - 单引号：字面量，不解析转义；双引号：解析 \n \t \r \" \\ 转义
+* - 无引号：去掉行尾 ` #...` 内联注释（前必须有空白），并 trim
+* - 同名键后者覆盖前者
+* - 非法行抛错并带上行号（fail fast：配置写错不该静默忽略）
+*/
+function parseEnvFile(text) {
+	const out = {};
+	const lines = text.split(/\r?\n/);
+	for (let i = 0; i < lines.length; i++) {
+		const raw = lines[i] ?? "";
+		const line = raw.trim();
+		if (line === "" || line.startsWith("#")) continue;
+		const body = line.startsWith("export ") ? line.slice(7).trim() : line;
+		const eq = body.indexOf("=");
+		if (eq <= 0) throw new Error(`配置文件第 ${i + 1} 行不是 KEY=VALUE：${raw.slice(0, 80)}`);
+		const key = body.slice(0, eq).trim();
+		if (!KEY_RE.test(key)) throw new Error(`配置文件第 ${i + 1} 行的变量名非法：${key}`);
+		out[key] = unquote(body.slice(eq + 1).trim());
+	}
+	return out;
+}
+function unquote(value) {
+	if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) return value.slice(1, -1);
+	if (value.length >= 2 && value.startsWith("\"") && value.endsWith("\"")) return value.slice(1, -1).replace(/\\([nrt"\\])/g, (_m, c) => c === "n" ? "\n" : c === "r" ? "\r" : c === "t" ? "	" : c);
+	const hash = value.search(/\s#/);
+	return (hash === -1 ? value : value.slice(0, hash)).trim();
+}
+/**
+* 定位配置文件，按优先级返回第一个存在的：
+* 1. 显式 path / `HOMURA_CONFIG_FILE`
+* 2. `<cwd>/homura.config.env`（= 部署产物根，随产物携带的那份）
+* 3. `<QWENWORK_WRITABLE_DIR>/homura.config.env`（平台可写区：可在不改产物的情况下投放/轮换）
+* 4. extraDirs 下的同名文件
+* 都不存在返回 null（零配置也能跑——渐进式）。
+*/
+function resolveConfigFilePath(env, opts = {}) {
+	const cwd = opts.cwd ?? process.cwd();
+	const explicit = opts.path ?? env["HOMURA_CONFIG_FILE"];
+	const candidates = [];
+	if (explicit) candidates.push(isAbsolute(explicit) ? explicit : resolve(cwd, explicit));
+	candidates.push(resolve(cwd, CONFIG_FILE_NAME));
+	const writable = env["QWENWORK_WRITABLE_DIR"];
+	if (writable) candidates.push(resolve(writable, CONFIG_FILE_NAME));
+	for (const dir of opts.extraDirs ?? []) candidates.push(resolve(dir, CONFIG_FILE_NAME));
+	return candidates.find((p) => existsSync(p)) ?? null;
+}
+/**
+* 把配置文件并入 env（就地修改传入对象，通常就是 process.env）。
+* 必须在 defineConfig(...).load(env) **之前**调用。
+*/
+function applyEnvFile(env, opts = {}) {
+	const path = resolveConfigFilePath(env, opts);
+	if (!path) return {
+		path: null,
+		applied: [],
+		skipped: []
+	};
+	const values = parseEnvFile(readFileSync(path, "utf8"));
+	const applied = [];
+	const skipped = [];
+	for (const [key, value] of Object.entries(values)) {
+		const existing = env[key];
+		if (!opts.override && existing !== void 0 && existing !== "") {
+			skipped.push(key);
+			continue;
+		}
+		env[key] = value;
+		applied.push(key);
+	}
+	return {
+		path,
+		applied,
+		skipped
+	};
+}
+//#endregion
 //#region src/logger.ts
 const LEVEL_ORDER = {
 	debug: 10,
@@ -161,4 +283,4 @@ function randomToken(bytes) {
 	return randomBytes(bytes).toString("base64url");
 }
 //#endregion
-export { QW_PAGES_ENV_MARKERS, createLogger, createMemoryTtlKv, defineConfig, detectRuntime, parses, randomToken };
+export { CONFIG_FILE_NAME, HEALTHZ_PATH, QW_PAGES_ENV_MARKERS, applyEnvFile, createLogger, createMemoryTtlKv, defineConfig, detectRuntime, healthzPathFor, parseEnvFile, parses, randomToken, resolveConfigFilePath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homurajs/core",
-  "version": "26.10.13",
+  "version": "26.10.14",
   "type": "module",
   "description": "homura 基座：运行环境探测、配置装载、日志、TTL-KV",
   "engines": {