@homurajs/core 0.0.0-stage → 26.10.13

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @homurajs/core
 
-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.
+基座包（零依赖）：运行环境探测、配置装载、结构化日志、TTL-KV。
+
+```ts
+import { detectRuntime, defineConfig, parses, createLogger, createMemoryTtlKv } from '@homurajs/core'
+
+// 1. 环境：HOMURA_RUNTIME 显式优先，QW_PAGES* 标记启发式
+const { target } = detectRuntime(process.env) // 'standalone' | 'qw-pages'
+
+// 2. 配置即文档：load() + 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
+const log = createLogger().child('auth')
+log.info('登录成功', { userId: 'u1' })
+
+// 4. 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()`）。

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+//#region src/runtime.d.ts
+/**
+ * 运行环境探测。
+ *
+ * 显式配置（HOMURA_RUNTIME）永远优先；探测仅为零配置体验的缺省，
+ * 标记列表集中在 QW_PAGES_ENV_MARKERS，属启发式，可被显式值覆盖。
+ */
+export type RuntimeTarget = 'standalone' | 'qw-pages';
+export interface RuntimeInfo {
+  target: RuntimeTarget;
+  /** true = 来自显式 env；false = 启发式探测 */
+  explicit: boolean;
+  /** 探测依据（explicit=false 时给出命中的标记） */
+  reasons: string[];
+}
+/** qw-pages 环境的启发式标记（文档标注：启发式、可被 HOMURA_RUNTIME 覆盖） */
+export declare const QW_PAGES_ENV_MARKERS: readonly string[];
+export declare function detectRuntime(env: NodeJS.ProcessEnv): RuntimeInfo;
+//#endregion
+//#region src/config.d.ts
+/**
+ * 类型安全的配置装载：配置即文档。
+ *
+ * defineConfig(specs) 返回 { load, help }：
+ * - load(env?) 解析并校验环境变量（未显式传 env 时自动 process.loadEnvFile()）
+ * - help() 生成 .env.example 片段
+ */
+export interface ConfigSpec<T> {
+  /** 环境变量名 */
+  env: string;
+  default?: T;
+  parse: (raw: string) => T;
+  /** true = 缺失且无 default 即抛错 */
+  required?: boolean;
+  /** true = help() 输出时打码 */
+  secret?: boolean;
+  /** 人类可读说明（help() 输出与 .env.example 注释） */
+  description?: string;
+}
+export interface LoadedConfig<S extends Record<string, ConfigSpec<unknown>>> {
+  /** 按 spec key 取已解析值 */
+  get<K extends keyof S & string>(key: K): S[K] extends ConfigSpec<infer T> ? T : never;
+  /** 原始解析结果（测试用） */
+  raw(): { [K in keyof S]: S[K] extends ConfigSpec<infer T> ? T | undefined : never; };
+}
+export declare function defineConfig<S extends Record<string, ConfigSpec<unknown>>>(specs: S): {
+  load(env?: NodeJS.ProcessEnv): LoadedConfig<S>;
+  /** 生成 .env.example 片段——配置即文档 */
+  help(): string;
+};
+/** 常用 parse 助手 */
+export declare const parses: {
+  readonly string: (raw: string) => string;
+  readonly int: (raw: string) => number;
+  readonly boolean: (raw: string) => boolean;
+};
+//#endregion
+//#region src/logger.d.ts
+/**
+ * 结构化日志（轻量零依赖实现）：JSON lines 输出，便于 qw-pages 等平台收集。
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface Logger {
+  debug(msg: string, fields?: Record<string, unknown>): void;
+  info(msg: string, fields?: Record<string, unknown>): void;
+  warn(msg: string, fields?: Record<string, unknown>): void;
+  error(msg: string, fields?: Record<string, unknown>): void;
+  /** 派生带固定 scope 的子 logger */
+  child(scope: string): Logger;
+}
+export declare function createLogger(options?: {
+  level?: LogLevel;
+  /** 输出中打码的字段名（默认 ['secret','password','token','authorization','apikey']） */
+  redactKeys?: string[];
+}): Logger;
+//#endregion
+//#region src/ttlkv.d.ts
+export interface TtlKv {
+  set(key: string, value: string, ttlMs: number): Promise<void>;
+  /** 一次性取出并删除（CSRF state 消费语义）；过期返回 null */
+  take(key: string): Promise<string | null>;
+}
+export declare function createMemoryTtlKv(options?: {
+  maxEntries?: number;
+}): TtlKv;
+/** 加密随机串（base64url），state/token 生成用 */
+export declare function randomToken(bytes: number): string;
+//#endregion

package/dist/index.js

@@ -0,0 +1,164 @@
+import { randomBytes } from "node:crypto";
+//#region src/runtime.ts
+/** qw-pages 环境的启发式标记（文档标注：启发式、可被 HOMURA_RUNTIME 覆盖） */
+const QW_PAGES_ENV_MARKERS = ["QW_PAGES", "QW_PAGES_APP_ID"];
+function detectRuntime(env) {
+	const explicit = env["HOMURA_RUNTIME"];
+	if (explicit !== void 0) {
+		if (explicit !== "standalone" && explicit !== "qw-pages") throw new Error(`HOMURA_RUNTIME 非法值: ${explicit}（允许 'standalone' | 'qw-pages'）`);
+		return {
+			target: explicit,
+			explicit: true,
+			reasons: [`HOMURA_RUNTIME=${explicit}`]
+		};
+	}
+	const hits = QW_PAGES_ENV_MARKERS.filter((m) => env[m] !== void 0 && env[m] !== "");
+	if (hits.length > 0) return {
+		target: "qw-pages",
+		explicit: false,
+		reasons: hits
+	};
+	return {
+		target: "standalone",
+		explicit: false,
+		reasons: []
+	};
+}
+//#endregion
+//#region src/config.ts
+function defineConfig(specs) {
+	const loadFrom = (env) => {
+		const out = {};
+		for (const [key, spec] of Object.entries(specs)) {
+			const raw = env[spec.env];
+			if (raw !== void 0 && raw !== "") out[key] = spec.parse(raw);
+			else if (spec.default !== void 0) out[key] = spec.default;
+			else if (spec.required) throw new Error(`缺少必需的环境变量 ${spec.env}（配置项 ${key}）`);
+			else out[key] = void 0;
+		}
+		return out;
+	};
+	return {
+		load(env) {
+			let source = env;
+			if (!source) {
+				try {
+					process.loadEnvFile();
+				} catch {}
+				source = process.env;
+			}
+			const resolved = loadFrom(source);
+			return {
+				get: ((key) => {
+					if (!(key in resolved)) throw new Error(`未知配置项: ${key}`);
+					return resolved[key];
+				}),
+				raw: () => resolved
+			};
+		},
+		help() {
+			const lines = ["# 由 @homurajs/core defineConfig 生成（配置即文档）", ""];
+			for (const [key, spec] of Object.entries(specs)) {
+				if (spec.description) lines.push(`# ${spec.description}`);
+				const example = spec.secret ? `${spec.env}=<redacted>` : `${spec.env}=${spec.default ?? ""}`;
+				lines.push(`${example}`);
+				lines.push("");
+			}
+			return lines.join("\n");
+		}
+	};
+}
+/** 常用 parse 助手 */
+const parses = {
+	string: (raw) => raw,
+	int: (raw) => {
+		const n = Number.parseInt(raw, 10);
+		if (Number.isNaN(n)) throw new Error(`not an integer: ${raw}`);
+		return n;
+	},
+	boolean: (raw) => raw === "1" || raw.toLowerCase() === "true"
+};
+//#endregion
+//#region src/logger.ts
+const LEVEL_ORDER = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40
+};
+const DEFAULT_REDACT = [
+	"secret",
+	"password",
+	"token",
+	"authorization",
+	"apikey"
+];
+function createLogger(options) {
+	const level = options?.level ?? "info";
+	const redactKeys = options?.redactKeys ?? DEFAULT_REDACT;
+	const redactSet = new Set(redactKeys.map((k) => k.toLowerCase()));
+	const emit = (lvl, scopes, msg, fields) => {
+		if (LEVEL_ORDER[lvl] < LEVEL_ORDER[level]) return;
+		const safeFields = {};
+		for (const [k, v] of Object.entries(fields ?? {})) safeFields[k] = redactSet.has(k.toLowerCase()) ? "[REDACTED]" : v;
+		const line = {
+			ts: (/* @__PURE__ */ new Date()).toISOString(),
+			level: lvl,
+			...scopes.length > 0 ? { scope: scopes.join(":") } : {},
+			msg,
+			...safeFields
+		};
+		const out = JSON.stringify(line);
+		if (lvl === "error") console.error(out);
+		else if (lvl === "warn") console.warn(out);
+		else console.log(out);
+	};
+	const make = (scopes) => ({
+		debug: (m, f) => emit("debug", scopes, m, f),
+		info: (m, f) => emit("info", scopes, m, f),
+		warn: (m, f) => emit("warn", scopes, m, f),
+		error: (m, f) => emit("error", scopes, m, f),
+		child: (scope) => make([...scopes, scope])
+	});
+	return make([]);
+}
+//#endregion
+//#region src/ttlkv.ts
+/**
+* TTL-KV 抽象：OAuth state 等「一次性消费」语义的最小存储。
+* 内存实现为缺省；多实例部署用 @homurajs/db 的 createDbTtlKv 兜底。
+*/
+function createMemoryTtlKv(options) {
+	const maxEntries = options?.maxEntries ?? 1e4;
+	const store = /* @__PURE__ */ new Map();
+	const sweep = (now) => {
+		for (const [k, e] of store) if (e.expiresAt <= now) store.delete(k);
+	};
+	return {
+		async set(key, value, ttlMs) {
+			const now = Date.now();
+			if (store.size >= maxEntries) sweep(now);
+			if (store.size >= maxEntries) {
+				const oldest = store.keys().next().value;
+				if (oldest !== void 0) store.delete(oldest);
+			}
+			store.set(key, {
+				value,
+				expiresAt: now + ttlMs
+			});
+		},
+		async take(key) {
+			const entry = store.get(key);
+			if (!entry) return null;
+			store.delete(key);
+			if (entry.expiresAt <= Date.now()) return null;
+			return entry.value;
+		}
+	};
+}
+/** 加密随机串（base64url），state/token 生成用 */
+function randomToken(bytes) {
+	return randomBytes(bytes).toString("base64url");
+}
+//#endregion
+export { QW_PAGES_ENV_MARKERS, createLogger, createMemoryTtlKv, defineConfig, detectRuntime, parses, randomToken };

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@homurajs/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "26.10.13",
+  "type": "module",
+  "description": "homura 基座：运行环境探测、配置装载、日志、TTL-KV",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "tsdown": "^0.23.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }