@ubean/shared 0.2.0

package/LICENSE

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

@@ -0,0 +1,447 @@
+import { Context, Env, Handler, MiddlewareHandler } from "hono";
+import { RequestIdVariables } from "hono/request-id";
+import { HandlerResponse, Input as Input$1 } from "hono/types";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/types.d.ts
+/**
+ * 基础路由元数据,由 @ubean/scan 使用。
+ * 扩展的 RouteMeta 在此处定义,增加了 rateLimit 和 cache 字段。
+ */
+interface BaseRouteMeta {
+  requiresAuth?: boolean;
+  [key: string]: unknown;
+}
+interface RateLimitMeta {
+  maxRequests: number;
+  windowSeconds: number;
+}
+interface CacheMeta {
+  ttl: number;
+  swr?: boolean;
+}
+interface RouteMeta extends BaseRouteMeta {
+  rateLimit?: RateLimitMeta;
+  cache?: CacheMeta;
+}
+/**
+ * ISR (Incremental Static Regeneration) 规则。
+ *
+ * - `number` → `{ ttl: <秒数>, swr: false }` 的简写
+ * - 对象形式可显式指定 `swr` 启用 stale-while-revalidate 语义
+ *   (返回过期内容 + 后台异步重新生成)
+ */
+interface IsrRule {
+  /** 缓存有效期(秒)。过期后下次请求触发重新生成 */
+  ttl: number;
+  /** 是否启用 stale-while-revalidate:过期时先返回旧内容,后台异步刷新 */
+  swr?: boolean;
+}
+/**
+ * 路由规则,由 @ubean/routes (route-rules) 和 @ubean/server (cache) 共享。
+ * 完整的 ResolvedConfig 在 @ubean/config 中定义。
+ *
+ * P9-03 扩展:支持 per-route 渲染规则(`ssr`/`prerender`/`isr`)。
+ * 这些字段为运行时 / 构建时的渲染提示,与原有的 `cache`/`headers`/`redirect`/
+ * `rewrite`/`proxy` 等运行时规则并存:
+ *
+ * - `ssr: true`        强制该路由走 SSR(覆盖全局 `ssr.exclude`)
+ * - `ssr: false`       强制该路由跳过 SSR(走 CSR shell)
+ * - `ssr: 'streaming'` 强制该路由走流式 SSR(覆盖全局 `ssr.streaming`)
+ * - `prerender: true`  该路由加入 SSG 预渲染队列(由 `@ubean/prerender` 自动发现)
+ * - `isr: 60` 或 `isr: { ttl: 60, swr: true }`  启用 ISR,以 TTL 秒缓存渲染 HTML
+ *
+ * P9-04 扩展:支持 Partial Prerendering(`ppr`)。
+ * - `ppr: true` 启用 PPR:静态壳预渲染 + Suspense 流式动态内容
+ *   (对齐 Next.js 16 PPR / Astro `server:defer`)。运行时强制流式 SSR,
+ *   覆盖全局 `ssr.exclude`;同时该路由加入预渲染队列(等价于 `prerender: true`),
+ *   预渲染产物作为静态壳供运行时复用。
+ *
+ * 注意:构建时预渲染策略已迁移至 `PrerenderConfig`(由 `ubean.config.ts` 的
+ * `prerender` 字段统一管理),`RouteRule.prerender` 仅作为自动发现标记 ——
+ * `prerender: true` 的路由会被 `collectPrerenderRoutes` 加入队列(受
+ * `PrerenderConfig.exclude` 过滤)。`ppr: true` 隐含 `prerender: true`。
+ */
+interface RouteRule {
+  cache?: {
+    ttl?: number;
+    swr?: boolean;
+  };
+  headers?: Record<string, string>;
+  redirect?: string | {
+    to: string;
+    statusCode?: number;
+  };
+  rewrite?: string;
+  proxy?: string;
+  /**
+   * Per-route SSR 渲染策略(P9-03)。覆盖全局 `ssr.exclude` / `ssr.streaming`。
+   *
+   * - `true`  强制 SSR(即使命中全局 exclude)
+   * - `false` 强制 CSR(即使全局未排除)
+   * - `'streaming'` 强制流式 SSR(等同于 `ssr: true` + 流式输出)
+   */
+  ssr?: boolean | 'streaming';
+  /**
+   * 标记该路由加入 SSG 预渲染队列(P9-03)。
+   * 由 `collectPrerenderRoutes` 自动从 `routeRules` 中扫描发现。
+   */
+  prerender?: boolean;
+  /**
+   * 启用 ISR(增量静态再生,P9-03)。
+   *
+   * 服务端将渲染后的 HTML 以 TTL 秒缓存;过期后下次请求触发重新生成。
+   * `swr: true` 时,过期窗口内先返回旧 HTML,同时后台异步刷新。
+   */
+  isr?: number | IsrRule;
+  /**
+   * 启用 Partial Prerendering / Server Islands(P9-04)。
+   *
+   * - `true` 该路由启用 PPR:静态壳预渲染 + Suspense 流式动态内容
+   *
+   * 运行时行为:
+   * - 强制流式 SSR(覆盖 `ssr.exclude` / 全局 `streaming`),等价于 `ssr: 'streaming'`
+   * - 隐含 `prerender: true`,该路由会被预渲染(产物作为静态壳)
+   * - 页面内带 `server:defer` 指令的组件在预渲染时仅渲染 fallback,
+   *   在流式 SSR 时通过 Suspense 边界流式输出实际内容
+   *
+   * 对齐:Next.js 16 PPR(稳定)、Astro 5 `server:defer`。
+   */
+  ppr?: boolean;
+}
+type SpanStatus = 'ok' | 'error' | 'cancelled';
+interface SpanAttributes {
+  [key: string]: string | number | boolean | undefined | null;
+}
+interface SpanContext {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+}
+interface SpanEndOptions {
+  status?: SpanStatus;
+  error?: Error;
+  attributes?: SpanAttributes;
+}
+interface SpanEvent {
+  name: string;
+  timestamp: number;
+  attributes?: SpanAttributes;
+}
+interface SpanOptions {
+  name: string;
+  attributes?: SpanAttributes;
+  parent?: Span | SpanContext;
+}
+interface Span {
+  readonly name: string;
+  readonly context: SpanContext;
+  readonly startTime: number;
+  endTime?: number;
+  status: SpanStatus;
+  attributes: SpanAttributes;
+  events: SpanEvent[];
+  error?: Error;
+  parent?: Span;
+  end(options?: SpanEndOptions): void;
+  setAttribute(key: string, value: string | number | boolean | undefined | null): void;
+  setAttributes(attrs: SpanAttributes): void;
+  addEvent(name: string, attributes?: SpanAttributes): void;
+  isRecording(): boolean;
+  duration(): number | undefined;
+}
+interface PageHead {
+  title?: string;
+  meta?: Array<Record<string, string>>;
+  link?: Array<Record<string, string>>;
+  script?: Array<Record<string, string>>;
+  htmlAttrs?: Record<string, string>;
+  bodyAttrs?: Record<string, string>;
+}
+interface UbeanVariables extends RequestIdVariables {
+  route: {
+    meta: RouteMeta;
+    path: string;
+    method: string;
+  };
+  span?: Span;
+  locale?: string;
+  pathWithoutLocale?: string;
+  /**
+   * 匹配到的路由规则(P9-03)。由 `createRouteRulesMiddleware` 在请求开始时
+   * 写入,供页面渲染器读取 per-route 的 `ssr`/`isr`/`prerender` 等字段。
+   * 未启用 routeRules 中间件时为 `undefined`。
+   */
+  routeRule?: RouteRule;
+}
+interface UbeanBindings {}
+interface UbeanEnv extends Env {
+  Variables: UbeanVariables;
+  Bindings: UbeanBindings;
+}
+type UbeanContext = Context<UbeanEnv>;
+type Input = Input$1;
+interface GenericSchema<O = unknown> {
+  safeParse?(value: unknown): {
+    success: boolean;
+    data?: O;
+    error?: {
+      issues?: Array<{
+        message?: string;
+      }>;
+    };
+  };
+  parse?(value: unknown): O;
+  _output?: O;
+}
+type UbeanMiddleware<I extends Input = {}> = MiddlewareHandler<UbeanEnv, any, I>;
+type UbeanHandler<I extends Input = {}, R extends HandlerResponse<any> = HandlerResponse<any>> = Handler<UbeanEnv, any, I, R>;
+type ComposedHandler = MiddlewareHandler<UbeanEnv>;
+/**
+ * Action ID — a stable string identifier for a server action.
+ *
+ * Generated from the action's source location (file path + export name) so
+ * the client and server sides agree on the same ID without runtime
+ * coordination. Format: `<base32(sha1(relPath:exportName))>`.
+ */
+type ActionId = string;
+/**
+ * Context passed to every server action handler.
+ *
+ * - `request`: the underlying `Request` (for headers, cookies, etc.)
+ * - `context`: the Hono context (for `c.set`, `c.get`, `c.req`, etc.)
+ * - `params`: route params extracted from the URL (for page-level actions)
+ */
+interface ActionContext {
+  request: Request;
+  context: Context<UbeanEnv>;
+  params: Record<string, string>;
+}
+/**
+ * Result returned by a server action.
+ *
+ * - `data`: the action's return value (serializable)
+ * - `error`: an `ActionError` instance thrown by the handler, or `null`
+ * - `errors`: per-field validation errors (SvelteKit-style `ActionFailure<{ fields }>`),
+ *   populated when the handler returns `fail()` with field errors
+ * - `response`: a raw `Response` returned/thrown by the handler (e.g. a
+ *   redirect) — passed through verbatim by the dispatcher instead of being
+ *   JSON-serialized
+ *
+ * Either `data` (success), `error`/`errors` (failure), or `response`
+ * (passthrough) is set; never more than one.
+ */
+interface ActionResult<T = unknown> {
+  data?: T;
+  error?: {
+    message: string;
+    code?: string;
+  };
+  errors?: Record<string, string> | null;
+  response?: Response;
+  status: number;
+}
+/**
+ * A handler that runs server-side when an action is invoked.
+ *
+ * - When `schema` is provided to `defineAction`, the handler receives the
+ *   parsed/validated `data` (typed by the schema's output).
+ * - Without a schema, the handler receives the raw `input` (FormData or
+ *   parsed JSON object).
+ *
+ * The handler may return any serializable value, throw an `ActionError`,
+ * or call `fail()` to return field-level validation errors.
+ */
+type ActionHandler<TInput = unknown, TOutput = unknown> = (input: TInput, ctx: ActionContext) => Promise<TOutput | ActionFailure> | TOutput | ActionFailure;
+/**
+ * Field-level validation failure (SvelteKit-style).
+ *
+ * Returned by `fail()` inside an action handler to signal validation errors
+ * back to the form without throwing. The page can read `result.errors` to
+ * display per-field messages.
+ */
+interface ActionFailure<T = Record<string, string>> {
+  __actionFailure: true;
+  status: number;
+  errors: T;
+}
+/**
+ * Schema accepted by `defineAction` for input validation.
+ *
+ * Any Standard Schema (`safeParse`/`parse`) or a function
+ * `(value: unknown) => { success: true; data } | { success: false; error }`.
+ */
+interface ActionSchema<TOutput = unknown> {
+  safeParse?(value: unknown): {
+    success: boolean;
+    data?: TOutput;
+    error?: {
+      issues?: Array<{
+        message?: string;
+      }>;
+    };
+  };
+  parse?(value: unknown): TOutput;
+  _output?: TOutput;
+}
+/**
+ * A registered server action — the runtime representation produced by
+ * `defineAction`. Carries the action ID and the original handler.
+ *
+ * The function is callable server-side (direct invocation with typed input)
+ * and is replaced by an RPC stub on the client (POST to `/__actions`).
+ */
+interface ServerAction<TInput = unknown, TOutput = unknown> {
+  /** Stable action ID (file path + export name hash). */
+  id: ActionId;
+  /** The handler that runs server-side. */
+  handler: ActionHandler<TInput, TOutput>;
+  /** Optional schema for input validation. */
+  schema?: ActionSchema<TOutput>;
+  /** Original function name (for error messages / debugging). */
+  name: string;
+  /** Source file path (project-relative, for debugging). */
+  filePath?: string;
+}
+/**
+ * Brand used to identify a server action at runtime (`Symbol`).
+ */
+declare const ACTION_BRAND: unique symbol;
+/**
+ * Type guard: is the value a registered `ServerAction`?
+ */
+declare function isServerAction(value: unknown): value is ServerAction;
+/**
+ * Error thrown by action handlers to signal a user-facing error.
+ *
+ * The `code` field can be used for programmatic error handling on the client
+ * (e.g. `err.code === 'INVALID_CREDENTIALS'`).
+ */
+declare class ActionError extends Error {
+  code?: string;
+  status: number;
+  constructor(message: string, opts?: {
+    code?: string;
+    status?: number;
+  });
+}
+/**
+ * Mark a return value as a field-level validation failure.
+ *
+ * Used inside `defineAction` handlers to signal validation errors back to
+ * the form without throwing. Mirrors SvelteKit's `fail()` helper.
+ *
+ * ```ts
+ * export const login = defineAction(async (input) => {
+ *   if (!input.email) return fail(400, { email: 'Email is required' });
+ *   return { user: input.email };
+ * });
+ * ```
+ */
+declare function fail<T extends Record<string, string>>(status: number, errors: T): ActionFailure<T>;
+/**
+ * Type guard: is the value an `ActionFailure` (returned by `fail()`)?
+ */
+declare function isActionFailure(value: unknown): value is ActionFailure;
+//#endregion
+//#region src/error.d.ts
+declare class UbeanError extends Error {
+  statusCode: number;
+  statusMessage: string;
+  data?: unknown;
+  constructor(statusCode: number, statusMessage?: string, data?: unknown);
+}
+declare function createError(options: {
+  statusCode: number;
+  statusMessage?: string;
+  data?: unknown;
+  message?: string;
+}): UbeanError;
+declare function isUbeanError(err: unknown): err is UbeanError;
+declare function errorToResponse(c: unknown, err?: unknown): Response;
+//#endregion
+//#region src/env.d.ts
+type EnvSchema = Record<string, StandardSchemaV1 | GenericSchema | {
+  type: StringConstructor | NumberConstructor | BooleanConstructor;
+  default?: unknown;
+  required?: boolean;
+}>;
+type InferEnvOutput<S extends EnvSchema> = { [K in keyof S]: S[K] extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S[K]> : S[K] extends GenericSchema<infer O> ? O : S[K] extends {
+  type: StringConstructor;
+} ? string : S[K] extends {
+  type: NumberConstructor;
+} ? number : S[K] extends {
+  type: BooleanConstructor;
+} ? boolean : string; };
+interface EnvConfig<S extends EnvSchema = EnvSchema> {
+  /** Server-only env variables (not exposed to client) */
+  server?: S;
+  /** Public env variables (exposed to client via import.meta.env) */
+  public?: S;
+  /** Validation mode - 'warn' logs errors, 'throw' throws on validation failure */
+  mode?: 'warn' | 'throw';
+}
+interface DefineEnvResult<S extends EnvSchema> {
+  readonly env: InferEnvOutput<S>;
+  validate(source?: Record<string, string | undefined>): {
+    success: boolean;
+    errors: EnvValidationError[];
+    data: InferEnvOutput<S>;
+  };
+}
+interface EnvValidationError {
+  key: string;
+  message: string;
+  value: unknown;
+}
+declare function defineEnv<S extends EnvSchema>(config: EnvConfig<S>): DefineEnvResult<S>;
+declare function setRuntimeEnv(env: Record<string, unknown>): void;
+declare function useRuntimeEnv<T = string>(key: string, defaultValue?: T): T;
+//#endregion
+//#region src/path.d.ts
+/**
+ * 标准化路径：替换反斜杠、去除首尾多余斜杠、合并连续斜杠。
+ */
+declare function normalizePath(path: string): string;
+/**
+ * 获取路径的目录部分（不含文件名）。
+ */
+declare function getDirname(path: string): string;
+/**
+ * 获取路径的文件名部分（含扩展名）。
+ */
+declare function getBasename(path: string): string;
+/**
+ * 获取文件名的扩展名（小写，不含点）。
+ */
+declare function getExtension(filename: string): string;
+/**
+ * 获取文件名（不含扩展名）。
+ */
+declare function getStem(filename: string): string;
+/**
+ * 将文件路径转换为人类可读的标题。
+ */
+declare function pathToTitle(path: string): string;
+//#endregion
+//#region src/glob.d.ts
+/**
+ * 通配符匹配,支持:
+ * - `**` 多段递归  ('/blog/**' 匹配 '/blog/a/b/c' 与 '/blog')
+ * - `*`  单段     ('/blog/*' 匹配 '/blog/a' 不匹配 '/blog/a/b')
+ * - 字面量         ('/about' 仅匹配 '/about')
+ *
+ * 提取自 `@ubean/prerender`,供 SSR exclude / prerender / 其他需要 glob 匹配的模块共享。
+ */
+declare function matchGlob(route: string, pattern: string): boolean;
+/**
+ * 检查 route 是否匹配任意一个 patterns。
+ */
+declare function matchAnyGlob(route: string, patterns: string[]): boolean;
+//#endregion
+//#region src/string.d.ts
+/**
+ * 将字符串首字母大写。
+ */
+declare function capitalize(str: string): string;
+//#endregion
+export { ACTION_BRAND, ActionContext, ActionError, ActionFailure, ActionHandler, ActionId, ActionResult, ActionSchema, BaseRouteMeta, CacheMeta, ComposedHandler, DefineEnvResult, EnvConfig, EnvSchema, EnvValidationError, GenericSchema, InferEnvOutput, Input, IsrRule, PageHead, RateLimitMeta, RouteMeta, RouteRule, ServerAction, Span, SpanAttributes, SpanContext, SpanEndOptions, SpanEvent, SpanOptions, SpanStatus, UbeanBindings, UbeanContext, UbeanEnv, UbeanError, UbeanHandler, UbeanMiddleware, UbeanVariables, capitalize, createError, defineEnv, errorToResponse, fail, getBasename, getDirname, getExtension, getStem, isActionFailure, isServerAction, isUbeanError, matchAnyGlob, matchGlob, normalizePath, pathToTitle, setRuntimeEnv, useRuntimeEnv };

package/dist/index.js

@@ -0,0 +1,339 @@
+import { kebabCase } from "scule";
+//#region src/types.ts
+/**
+* Brand used to identify a server action at runtime (`Symbol`).
+*/
+const ACTION_BRAND = Symbol.for("ubean.action");
+/**
+* Type guard: is the value a registered `ServerAction`?
+*/
+function isServerAction(value) {
+	return typeof value === "object" && value !== null && value[ACTION_BRAND] === true && typeof value.id === "string" && typeof value.handler === "function";
+}
+/**
+* Error thrown by action handlers to signal a user-facing error.
+*
+* The `code` field can be used for programmatic error handling on the client
+* (e.g. `err.code === 'INVALID_CREDENTIALS'`).
+*/
+var ActionError = class extends Error {
+	code;
+	status;
+	constructor(message, opts = {}) {
+		super(message);
+		this.name = "ActionError";
+		this.code = opts.code;
+		this.status = opts.status ?? 400;
+	}
+};
+/**
+* Mark a return value as a field-level validation failure.
+*
+* Used inside `defineAction` handlers to signal validation errors back to
+* the form without throwing. Mirrors SvelteKit's `fail()` helper.
+*
+* ```ts
+* export const login = defineAction(async (input) => {
+*   if (!input.email) return fail(400, { email: 'Email is required' });
+*   return { user: input.email };
+* });
+* ```
+*/
+function fail(status, errors) {
+	return {
+		__actionFailure: true,
+		status,
+		errors
+	};
+}
+/**
+* Type guard: is the value an `ActionFailure` (returned by `fail()`)?
+*/
+function isActionFailure(value) {
+	return typeof value === "object" && value !== null && value.__actionFailure === true;
+}
+//#endregion
+//#region src/error.ts
+var UbeanError = class extends Error {
+	statusCode;
+	statusMessage;
+	data;
+	constructor(statusCode, statusMessage, data) {
+		super(statusMessage);
+		this.name = "UbeanError";
+		this.statusCode = statusCode;
+		this.statusMessage = statusMessage || statusCodeToMessage(statusCode);
+		this.data = data;
+	}
+};
+function createError(options) {
+	return new UbeanError(options.statusCode, options.statusMessage || options.message, options.data);
+}
+function statusCodeToMessage(code) {
+	return {
+		400: "Bad Request",
+		401: "Unauthorized",
+		403: "Forbidden",
+		404: "Not Found",
+		405: "Method Not Allowed",
+		408: "Request Timeout",
+		409: "Conflict",
+		422: "Unprocessable Entity",
+		429: "Too Many Requests",
+		500: "Internal Server Error",
+		501: "Not Implemented",
+		502: "Bad Gateway",
+		503: "Service Unavailable"
+	}[code] || "Error";
+}
+function isErrorWithStatusCode(err) {
+	return err instanceof Error && "statusCode" in err && typeof err.statusCode === "number";
+}
+function isUbeanError(err) {
+	return err instanceof UbeanError || err instanceof Error && err.name === "UbeanError" && isErrorWithStatusCode(err);
+}
+function errorToResponse(c, err) {
+	const error = err ?? c;
+	if (isUbeanError(error)) return new Response(JSON.stringify({
+		error: error.statusMessage,
+		statusCode: error.statusCode,
+		data: error.data
+	}), {
+		status: error.statusCode,
+		headers: { "Content-Type": "application/json" }
+	});
+	const message = error instanceof Error ? error.message : String(error);
+	return new Response(JSON.stringify({
+		error: "Internal Server Error",
+		message
+	}), {
+		status: 500,
+		headers: { "Content-Type": "application/json" }
+	});
+}
+//#endregion
+//#region src/env.ts
+function parseSchemaValue(schema, rawValue, key) {
+	if (!schema) return {
+		ok: true,
+		value: rawValue
+	};
+	if ("~standard" in schema && typeof schema["~standard"] === "object" && schema["~standard"]) return {
+		ok: false,
+		error: "Standard schema validation requires async validate, use validate() instead"
+	};
+	if (typeof schema.safeParse === "function") {
+		const result = schema.safeParse(rawValue);
+		if (!result.success) return {
+			ok: false,
+			error: result.error?.issues?.[0]?.message || "invalid"
+		};
+		return {
+			ok: true,
+			value: result.data
+		};
+	}
+	if (schema.type === String) {
+		if (rawValue === void 0 || rawValue === "") {
+			if (schema.default !== void 0) return {
+				ok: true,
+				value: schema.default
+			};
+			if (schema.required === false) return {
+				ok: true,
+				value: void 0
+			};
+			return {
+				ok: false,
+				error: `Missing required env: ${key}`
+			};
+		}
+		return {
+			ok: true,
+			value: rawValue
+		};
+	}
+	if (schema.type === Number) {
+		if (rawValue === void 0 || rawValue === "") {
+			if (schema.default !== void 0) return {
+				ok: true,
+				value: schema.default
+			};
+			if (schema.required === false) return {
+				ok: true,
+				value: void 0
+			};
+			return {
+				ok: false,
+				error: `Missing required env: ${key}`
+			};
+		}
+		const n = Number(rawValue);
+		if (Number.isNaN(n)) return {
+			ok: false,
+			error: `Env ${key} must be a number, got ${rawValue}`
+		};
+		return {
+			ok: true,
+			value: n
+		};
+	}
+	if (schema.type === Boolean) {
+		if (rawValue === void 0 || rawValue === "") {
+			if (schema.default !== void 0) return {
+				ok: true,
+				value: schema.default
+			};
+			if (schema.required === false) return {
+				ok: true,
+				value: void 0
+			};
+			return {
+				ok: false,
+				error: `Missing required env: ${key}`
+			};
+		}
+		return {
+			ok: true,
+			value: rawValue === "true" || rawValue === "1"
+		};
+	}
+	return {
+		ok: true,
+		value: rawValue
+	};
+}
+function validateSchemaSync(schema, source) {
+	const errors = [];
+	const data = {};
+	for (const [key, def] of Object.entries(schema)) {
+		const rawValue = source[key];
+		const result = parseSchemaValue(def, rawValue, key);
+		if (!result.ok) errors.push({
+			key,
+			message: result.error || "invalid",
+			value: rawValue
+		});
+		else data[key] = result.value;
+	}
+	return {
+		success: errors.length === 0,
+		errors,
+		data
+	};
+}
+function defineEnv(config) {
+	const serverSource = typeof process !== "undefined" ? process.env : globalThis.process?.env || {};
+	const mergedSchema = {
+		...config.public,
+		...config.server
+	};
+	const initial = validateSchemaSync(mergedSchema, serverSource);
+	if (!initial.success && config.mode === "throw") {
+		const messages = initial.errors.map((e) => `  - ${e.key}: ${e.message}`).join("\n");
+		throw new Error(`Environment validation failed:\n${messages}`);
+	}
+	return {
+		env: new Proxy(initial.data, { get(target, prop) {
+			if (typeof prop === "string") return target[prop];
+		} }),
+		validate(source) {
+			return validateSchemaSync(mergedSchema, source || serverSource);
+		}
+	};
+}
+let _runtimeEnv = {};
+function setRuntimeEnv(env) {
+	_runtimeEnv = {
+		..._runtimeEnv,
+		...env
+	};
+}
+function useRuntimeEnv(key, defaultValue) {
+	return _runtimeEnv[key] ?? defaultValue;
+}
+//#endregion
+//#region src/string.ts
+/**
+* 将字符串首字母大写。
+*/
+function capitalize(str) {
+	return str.charAt(0).toUpperCase() + str.slice(1);
+}
+//#endregion
+//#region src/path.ts
+/**
+* 标准化路径：替换反斜杠、去除首尾多余斜杠、合并连续斜杠。
+*/
+function normalizePath(path) {
+	return `/${path.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/+$/, "").replace(/\/+/g, "/")}`;
+}
+/**
+* 获取路径的目录部分（不含文件名）。
+*/
+function getDirname(path) {
+	const parts = path.split("/");
+	parts.pop();
+	return parts.join("/") || "/";
+}
+/**
+* 获取路径的文件名部分（含扩展名）。
+*/
+function getBasename(path) {
+	const parts = path.split("/");
+	return parts[parts.length - 1];
+}
+/**
+* 获取文件名的扩展名（小写，不含点）。
+*/
+function getExtension(filename) {
+	const match = filename.match(/\.([^.]+)$/);
+	return match ? match[1].toLowerCase() : "";
+}
+/**
+* 获取文件名（不含扩展名）。
+*/
+function getStem(filename) {
+	return filename.replace(/\.[^.]+$/, "");
+}
+/**
+* 将文件路径转换为人类可读的标题。
+*/
+function pathToTitle(path) {
+	const stem = getStem(getBasename(path));
+	if (stem === "index") return kebabCase(getBasename(getDirname(path)) || "home").split("-").map(capitalize).join(" ");
+	return kebabCase(stem).split("-").map(capitalize).join(" ");
+}
+//#endregion
+//#region src/glob.ts
+/**
+* 通配符匹配,支持:
+* - `**` 多段递归  ('/blog/**' 匹配 '/blog/a/b/c' 与 '/blog')
+* - `*`  单段     ('/blog/*' 匹配 '/blog/a' 不匹配 '/blog/a/b')
+* - 字面量         ('/about' 仅匹配 '/about')
+*
+* 提取自 `@ubean/prerender`,供 SSR exclude / prerender / 其他需要 glob 匹配的模块共享。
+*/
+function matchGlob(route, pattern) {
+	if (pattern === route) return true;
+	if (pattern === "**") return true;
+	if (pattern.endsWith("/**")) {
+		const prefix = pattern.slice(0, -3);
+		return route === prefix || route.startsWith(`${prefix}/`);
+	}
+	if (pattern.endsWith("/*")) {
+		const prefix = pattern.slice(0, -2);
+		return route.startsWith(`${prefix}/`) && !route.slice(prefix.length + 1).includes("/");
+	}
+	if (pattern === "/**") return true;
+	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*");
+	return new RegExp(`^${escaped}$`).test(route);
+}
+/**
+* 检查 route 是否匹配任意一个 patterns。
+*/
+function matchAnyGlob(route, patterns) {
+	return patterns.some((p) => matchGlob(route, p));
+}
+//#endregion
+export { ACTION_BRAND, ActionError, UbeanError, capitalize, createError, defineEnv, errorToResponse, fail, getBasename, getDirname, getExtension, getStem, isActionFailure, isServerAction, isUbeanError, matchAnyGlob, matchGlob, normalizePath, pathToTitle, setRuntimeEnv, useRuntimeEnv };

package/dist/node.d.ts

@@ -0,0 +1,41 @@
+//#region src/port.d.ts
+interface FindPortOptions {
+  host?: string;
+  strictPort?: boolean;
+}
+/**
+ * Tries to listen on `port` at `host`. If the port is already in use and
+ * `strictPort` is false, recursively tries `port + 1` until an available
+ * port is found (mirrors Vite's behaviour).
+ *
+ * Resolves with the available port (which may differ from the requested one
+ * when not in strict mode). Rejects with the original error when the port is
+ * in use and `strictPort` is true, or for any non-EADDRINUSE error.
+ */
+declare function findAvailablePort(port: number, options?: FindPortOptions): Promise<number>;
+interface WaitForPortOptions {
+  host?: string;
+  retries?: number;
+  delay?: number;
+}
+/**
+ * Polls `port` until a TCP connection can be established, indicating the
+ * spawned preview server is ready to accept requests.
+ *
+ * Rejects when the port does not become available within `retries` attempts.
+ */
+declare function waitForPort(port: number, options?: WaitForPortOptions): Promise<void>;
+/**
+ * Returns true when something is actively listening on `port` at `host`.
+ */
+declare function isPortReachable(port: number, host: string): Promise<boolean>;
+declare function sleep(ms: number): Promise<void>;
+//#endregion
+//#region src/vite-config.d.ts
+/**
+ * 检测项目根目录下是否存在 vite 配置文件。
+ * 返回找到的第一个文件的完整路径,如果都不存在则返回 null。
+ */
+declare function findUserViteConfig(cwd: string): string | null;
+//#endregion
+export { FindPortOptions, WaitForPortOptions, findAvailablePort, findUserViteConfig, isPortReachable, sleep, waitForPort };

package/dist/node.js

@@ -0,0 +1,92 @@
+import { createConnection, createServer } from "node:net";
+import { existsSync } from "node:fs";
+import { join } from "pathe";
+//#region src/port.ts
+/**
+* Tries to listen on `port` at `host`. If the port is already in use and
+* `strictPort` is false, recursively tries `port + 1` until an available
+* port is found (mirrors Vite's behaviour).
+*
+* Resolves with the available port (which may differ from the requested one
+* when not in strict mode). Rejects with the original error when the port is
+* in use and `strictPort` is true, or for any non-EADDRINUSE error.
+*/
+async function findAvailablePort(port, options = {}) {
+	const host = options.host ?? "localhost";
+	const strictPort = options.strictPort ?? false;
+	return new Promise((resolve, reject) => {
+		const server = createServer();
+		server.once("error", (err) => {
+			if (err.code === "EADDRINUSE" && !strictPort) {
+				server.close();
+				resolve(findAvailablePort(port + 1, options));
+			} else reject(err);
+		});
+		server.listen(port, host, () => {
+			const addr = server.address();
+			const actual = typeof addr === "object" && addr ? addr.port : port;
+			server.close(() => resolve(actual));
+		});
+	});
+}
+/**
+* Polls `port` until a TCP connection can be established, indicating the
+* spawned preview server is ready to accept requests.
+*
+* Rejects when the port does not become available within `retries` attempts.
+*/
+async function waitForPort(port, options = {}) {
+	const host = options.host ?? "localhost";
+	const retries = options.retries ?? 30;
+	const delay = options.delay ?? 200;
+	for (let attempt = 0; attempt < retries; attempt++) {
+		if (await isPortReachable(port, host)) return;
+		await sleep(delay);
+	}
+	throw new Error(`Port ${port} did not become ready after ${retries} attempts (${host}).`);
+}
+/**
+* Returns true when something is actively listening on `port` at `host`.
+*/
+function isPortReachable(port, host) {
+	return new Promise((resolve) => {
+		const socket = createConnection({
+			port,
+			host
+		});
+		let settled = false;
+		const done = (result) => {
+			if (settled) return;
+			settled = true;
+			socket.destroy();
+			resolve(result);
+		};
+		socket.once("connect", () => done(true));
+		socket.once("error", () => done(false));
+		setTimeout(() => done(false), 1e3);
+	});
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//#endregion
+//#region src/vite-config.ts
+const VITE_CONFIG_FILES = [
+	"vite.config.ts",
+	"vite.config.mts",
+	"vite.config.js",
+	"vite.config.mjs"
+];
+/**
+* 检测项目根目录下是否存在 vite 配置文件。
+* 返回找到的第一个文件的完整路径,如果都不存在则返回 null。
+*/
+function findUserViteConfig(cwd) {
+	for (const file of VITE_CONFIG_FILES) {
+		const fullPath = join(cwd, file);
+		if (existsSync(fullPath)) return fullPath;
+	}
+	return null;
+}
+//#endregion
+export { findAvailablePort, findUserViteConfig, isPortReachable, sleep, waitForPort };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ubean/shared",
+  "version": "0.2.0",
+  "description": "Shared protocol types, errors, env and universal utilities for ubean",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    }
+  },
+  "dependencies": {
+    "@standard-schema/spec": "1.1.0",
+    "hono": "4.13.2",
+    "pathe": "^2.0.3",
+    "scule": "^1.3.0",
+    "ufo": "1.6.4"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "7.0.2",
+    "vite-plus": "0.2.9"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit --skipLibCheck"
+  }
+}