@hokan/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 huyongle
+
+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/lib/index.d.ts

@@ -0,0 +1,51 @@
+import { createTracer, loggerSink, type HostLogger, type TraceEntry, type TraceSink, type Tracer, type TracerOptions } from './trace.js';
+export { createTracer, loggerSink };
+export type { HostLogger, TraceEntry, TraceSink, Tracer, TracerOptions };
+/**
+ * dsh-hokan 全部功能包共用的路由前缀（浏览器侧因运行时隔离需各自定义）。
+ */
+export declare const ROUTE_PREFIX = "/dsh-hokan";
+/**
+ * 宿主 Web 路由注册的请求形状（Node HTTP 子集）。
+ */
+export interface HostRequest {
+    method?: string;
+}
+/**
+ * 宿主 Web 路由注册的响应形状（Node HTTP 子集）。
+ */
+export interface HostResponse {
+    writeHead(statusCode: number, headers: Record<string, string>): void;
+    end(body?: string): void;
+}
+/**
+ * exact 路由声明。
+ */
+export interface ExactRoute {
+    kind: 'exact';
+    path: string;
+    handler: (request: HostRequest, response: HostResponse) => void;
+}
+/**
+ * 功能行宿主上下文的最小结构类型（DSH cordis 宿主注入）。
+ */
+export interface HostContext {
+    effect(setup: () => (() => void) | undefined, label?: string): void;
+    webServer: {
+        register(route: ExactRoute): () => void;
+    };
+    logger?: HostLogger;
+}
+/**
+ * 注册本功能行的 config 下发路由：GET /dsh-hokan/<featureId>/config.json。
+ * 浏览器半侧收不到行 config（DSH 客户端配置管线已知限制），经本路由补齐。
+ *
+ * @param context 功能行宿主上下文
+ * @param options 功能 id、回显的配置对象与可选 tracer
+ * @returns 注销函数
+ */
+export declare function serveRowConfig(context: HostContext, options: {
+    featureId: string;
+    config: unknown;
+    tracer?: Tracer;
+}): () => void;

package/lib/index.js

@@ -0,0 +1,50 @@
+import { createTracer, loggerSink } from './trace.js';
+export { createTracer, loggerSink };
+/**
+ * dsh-hokan 全部功能包共用的路由前缀（浏览器侧因运行时隔离需各自定义）。
+ */
+export const ROUTE_PREFIX = '/dsh-hokan';
+// JSON 响应头。
+const JSON_HEADERS = {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+};
+// 非 GET/HEAD 请求回 405；已处理返回 true。
+function rejectUnsupportedMethod(request, response) {
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+        response.writeHead(405, {});
+        response.end('');
+        return true;
+    }
+    return false;
+}
+/**
+ * 注册本功能行的 config 下发路由：GET /dsh-hokan/<featureId>/config.json。
+ * 浏览器半侧收不到行 config（DSH 客户端配置管线已知限制），经本路由补齐。
+ *
+ * @param context 功能行宿主上下文
+ * @param options 功能 id、回显的配置对象与可选 tracer
+ * @returns 注销函数
+ */
+export function serveRowConfig(context, options) {
+    const disposeRoute = context.webServer.register({
+        kind: 'exact',
+        path: ROUTE_PREFIX + '/' + options.featureId + '/config.json',
+        handler: (request, response) => {
+            const startedAt = performance.now();
+            if (rejectUnsupportedMethod(request, response))
+                return;
+            response.writeHead(200, JSON_HEADERS);
+            response.end(JSON.stringify({ feature: options.featureId, config: options.config ?? {} }));
+            if (options.tracer?.enabled) {
+                options.tracer.event('config-route.serve', {
+                    featureId: options.featureId,
+                    durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+                });
+            }
+        },
+    });
+    return () => {
+        disposeRoute();
+    };
+}

package/lib/trace.d.ts

@@ -0,0 +1,45 @@
+export interface TraceEntry {
+    timestamp: string;
+    scope: string;
+    event: string;
+    durationMs?: number;
+    slow?: boolean;
+    detail?: Record<string, unknown>;
+}
+export interface TraceSink {
+    write(entry: TraceEntry): void;
+}
+export interface HostLogger {
+    debug?(message: string): void;
+    info?(message: string): void;
+    warn?(message: string): void;
+    error?(message: string): void;
+}
+export interface TracerOptions {
+    scope: string;
+    enabled: boolean;
+    sink?: TraceSink;
+    slowMs?: number;
+}
+export interface Tracer {
+    readonly scope: string;
+    readonly enabled: boolean;
+    child(childScope: string): Tracer;
+    event(name: string, detail?: Record<string, unknown>): void;
+    measure<T>(name: string, operation: () => Promise<T>): Promise<T>;
+}
+/**
+ * 构造写入宿主 logger.debug 的 sink；logger 缺失时退回传入的 fallback（默认 console.log）。
+ *
+ * @param logger 宿主 logger（可选）
+ * @param fallback 无 logger 时的输出函数
+ * @returns TraceSink
+ */
+export declare function loggerSink(logger?: HostLogger, fallback?: (message: string) => void): TraceSink;
+/**
+ * 创建一个 tracer。disabled 时 event/measure 零输出零开销（守卫在入口）。
+ *
+ * @param options 作用域、开关、sink 与慢阈值
+ * @returns Tracer
+ */
+export declare function createTracer(options: TracerOptions): Tracer;

package/lib/trace.js

@@ -0,0 +1,59 @@
+// 默认慢阈值（毫秒）。
+const DEFAULT_SLOW_MS = 200;
+// JSON 行前缀；grep 'hokan-trace' 即得全部轨迹。
+const LINE_PREFIX = 'hokan-trace ';
+/**
+ * 构造写入宿主 logger.debug 的 sink；logger 缺失时退回传入的 fallback（默认 console.log）。
+ *
+ * @param logger 宿主 logger（可选）
+ * @param fallback 无 logger 时的输出函数
+ * @returns TraceSink
+ */
+export function loggerSink(logger, fallback) {
+    return {
+        write(entry) {
+            const line = LINE_PREFIX + JSON.stringify(entry);
+            if (logger?.debug)
+                logger.debug(line);
+            else
+                (fallback ?? console.log)(line);
+        },
+    };
+}
+/**
+ * 创建一个 tracer。disabled 时 event/measure 零输出零开销（守卫在入口）。
+ *
+ * @param options 作用域、开关、sink 与慢阈值
+ * @returns Tracer
+ */
+export function createTracer(options) {
+    const sink = options.sink ?? loggerSink();
+    const slowMs = options.slowMs ?? DEFAULT_SLOW_MS;
+    const emit = (name, fields, detail) => {
+        sink.write({ timestamp: new Date().toISOString(), scope: options.scope, event: name, ...fields, detail });
+    };
+    return {
+        scope: options.scope,
+        enabled: options.enabled,
+        child(childScope) {
+            return createTracer({ ...options, scope: options.scope + '.' + childScope });
+        },
+        event(name, detail) {
+            if (!options.enabled)
+                return;
+            emit(name, {}, detail);
+        },
+        async measure(name, operation) {
+            if (!options.enabled)
+                return operation();
+            const startedAt = performance.now();
+            try {
+                return await operation();
+            }
+            finally {
+                const durationMs = Math.round((performance.now() - startedAt) * 100) / 100;
+                emit(name, { durationMs, slow: durationMs >= slowMs });
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@hokan/core",
+  "version": "0.1.0",
+  "description": "dsh-hokan 功能包共享宿主助手与类型（普通库，不注册 bundle 行）",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YuluoY/dsh-hokan.git",
+    "directory": "packages/core"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "dev": "tsc -p tsconfig.json --watch"
+  }
+}