@zhin.js/client 1.0.17 → 1.1.0

package/client/app.ts

@@ -0,0 +1,228 @@
+import * as React from "react";
+
+export type AddRouteInput = {
+  path: string;
+  name: string;
+  element: React.ReactNode;
+  parent?: string | null;
+  icon?: React.ReactNode | string;
+  requiredPermissions?: string[];
+  requiredRoles?: string[];
+  meta?: {
+    hideInMenu?: boolean;
+    order?: number;
+    group?: string;
+    fullWidth?: boolean;
+  };
+};
+
+export type AddToolInput = {
+  id?: string;
+  name: string;
+  icon?: React.ReactNode;
+  parent?: string | null;
+  path?: string;
+};
+
+export type ConsoleRouteRecord = {
+  path: string;
+  name: string;
+  element: React.ReactNode;
+  parent: string | null;
+  icon?: React.ReactNode | string;
+  requiredPermissions?: string[];
+  requiredRoles?: string[];
+  meta?: {
+    hideInMenu?: boolean;
+    order?: number;
+    group?: string;
+    fullWidth?: boolean;
+  };
+};
+
+export type InternalToolRecord = {
+  id: string;
+  name: string;
+  icon?: React.ReactNode;
+  parent: string | null;
+  path?: string;
+};
+
+export type RouteTreeNode = ConsoleRouteRecord & { children: RouteTreeNode[] };
+export type ToolTreeNode = InternalToolRecord & { children: ToolTreeNode[] };
+
+type SidebarRenderer = (options: { routes: RouteTreeNode[] }) => React.ReactNode;
+type ToolbarRenderer = (options: { tools: ToolTreeNode[] }) => React.ReactNode;
+export type ConsoleRouteRenderer = (route: ConsoleRouteRecord) => React.ReactNode;
+
+const listeners = new Set<() => void>();
+let version = 0;
+
+function bump() {
+  version++;
+  for (const l of listeners) l();
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+function getVersion() {
+  return version;
+}
+
+let routes: ConsoleRouteRecord[] = [];
+let tools: InternalToolRecord[] = [];
+let sidebarRenderer: SidebarRenderer | null = null;
+let toolbarRenderer: ToolbarRenderer | null = null;
+let routeRenderer: ConsoleRouteRenderer | null = null;
+
+function slugId(name: string) {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-|-$/g, "") || "tool"
+  );
+}
+
+function buildRouteTree(flatRoutes: ConsoleRouteRecord[]): RouteTreeNode[] {
+  const nodes: RouteTreeNode[] = flatRoutes.map((r) => ({ ...r, children: [] }));
+  const roots: RouteTreeNode[] = [];
+
+  for (const node of nodes) {
+    if (!node.parent) {
+      roots.push(node);
+    } else {
+      const parent = nodes.find((n) => n.path === node.parent);
+      if (parent) {
+        parent.children.push(node);
+      } else {
+        roots.push(node);
+      }
+    }
+  }
+
+  const sortFn = (a: RouteTreeNode, b: RouteTreeNode) =>
+    (a.meta?.order ?? 999) - (b.meta?.order ?? 999);
+  roots.sort(sortFn);
+  for (const n of nodes) n.children.sort(sortFn);
+
+  return roots;
+}
+
+function buildToolTree(flatTools: InternalToolRecord[]): ToolTreeNode[] {
+  const nodes: ToolTreeNode[] = flatTools.map((t) => ({ ...t, children: [] }));
+  const roots: ToolTreeNode[] = [];
+
+  for (const node of nodes) {
+    if (!node.parent) {
+      roots.push(node);
+    } else {
+      const parent = nodes.find((n) => n.id === node.parent);
+      if (parent) {
+        parent.children.push(node);
+      } else {
+        roots.push(node);
+      }
+    }
+  }
+  return roots;
+}
+
+function renderRouteElement(route: ConsoleRouteRecord): React.ReactNode {
+  if (routeRenderer) return routeRenderer(route);
+  return route.element;
+}
+
+function createConsoleApp() {
+  return {
+    subscribe,
+    getVersion,
+
+    defineSidebar(render: SidebarRenderer) {
+      sidebarRenderer = render;
+      bump();
+    },
+
+    defineToolbar(render: ToolbarRenderer) {
+      toolbarRenderer = render;
+      bump();
+    },
+
+    defineRouter(render: ConsoleRouteRenderer) {
+      routeRenderer = render;
+      bump();
+    },
+
+    addRoute(input: AddRouteInput) {
+      const next = routes.filter((r) => r.path !== input.path);
+      next.push({
+        path: input.path,
+        name: input.name,
+        element: input.element,
+        parent: input.parent ?? null,
+        icon: input.icon,
+        requiredPermissions: input.requiredPermissions,
+        requiredRoles: input.requiredRoles,
+        meta: input.meta,
+      });
+      routes = next;
+      bump();
+    },
+
+    removeRoute(path: string) {
+      routes = routes.filter((r) => r.path !== path);
+      bump();
+    },
+
+    addTool(input: AddToolInput): string {
+      const id =
+        input.id ?? `${slugId(input.name)}-${Math.random().toString(36).slice(2, 8)}`;
+      if (tools.some((t) => t.id === id)) {
+        throw new Error(`[zhin-console] addTool: id already exists: ${id}`);
+      }
+      tools = [
+        ...tools,
+        {
+          id,
+          name: input.name,
+          icon: input.icon,
+          parent: input.parent ?? null,
+          path: input.path,
+        },
+      ];
+      bump();
+      return id;
+    },
+
+    getRouteTree(): RouteTreeNode[] {
+      return buildRouteTree(routes);
+    },
+
+    getToolTree(): ToolTreeNode[] {
+      return buildToolTree(tools);
+    },
+
+    _getRoutes(): readonly ConsoleRouteRecord[] {
+      return routes;
+    },
+
+    _getSidebarRenderer(): SidebarRenderer | null {
+      return sidebarRenderer;
+    },
+
+    _getToolbarRenderer(): ToolbarRenderer | null {
+      return toolbarRenderer;
+    },
+
+    _renderRouteElement(route: ConsoleRouteRecord): React.ReactNode {
+      return renderRouteElement(route);
+    },
+  };
+}
+
+export type ConsoleApp = ReturnType<typeof createConsoleApp>;
+
+export const app = createConsoleApp();

package/client/bootstrap/loadConsoleEntries.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it, vi } from "vitest";
+import { createPluginRegisterHostApi, getRegisterFn } from "./loadConsoleEntries.js";
+
+describe("console entries bootstrap", () => {
+  it("resolves named register export", () => {
+    const register = () => {};
+    expect(getRegisterFn({ register })).toBe(register);
+  });
+
+  it("resolves default register export", () => {
+    const register = () => {};
+    expect(getRegisterFn({ default: { register } })).toBe(register);
+  });
+
+  it("returns null when no register export exists", () => {
+    expect(getRegisterFn({ default: {} })).toBeNull();
+  });
+
+  it("creates a host API with addPage aliased to addRoute", () => {
+    const React = {} as any;
+    const addRoute = vi.fn();
+    const addTool = vi.fn(() => "tool-id");
+    const api = createPluginRegisterHostApi({ React, addRoute, addTool });
+
+    api.addPage({ path: "/x", name: "x", element: "page" as any });
+    api.addRoute({ path: "/y", name: "y", element: "route" as any });
+    expect(api.React).toBe(React);
+    expect(addRoute).toHaveBeenCalledTimes(2);
+    expect(api.addTool({ id: "t", name: "T" })).toBe("tool-id");
+  });
+});
+

package/client/bootstrap/loadConsoleEntries.ts

@@ -0,0 +1,149 @@
+import type {
+  ConsoleClientEntry,
+  ConsoleEntriesResponse,
+  ConsolePluginRegister,
+  PluginRegisterHostApi,
+} from "@zhin.js/console-types";
+import { DEFAULT_CONSOLE_BASE_PATH } from "@zhin.js/console-types";
+
+export type FetchConsoleEntriesOptions = {
+  entriesUrl?: string;
+  signal?: AbortSignal;
+  fetchInit?: RequestInit | (() => RequestInit);
+};
+
+export type LoadConsoleEntriesOptions = FetchConsoleEntriesOptions & {
+  /** Origin for `/@dev` / `/@assets` module URLs (Remote Console: Host API base). */
+  assetOrigin?: string;
+  hostApi: PluginRegisterHostApi;
+  beforeLoad?: () => void;
+  onEmpty?: () => void;
+  onFetchError?: (status: number) => void;
+  onEntryError?: (entry: ConsoleClientEntry, error: unknown) => void;
+};
+
+export type CreatePluginRegisterHostApiOptions = {
+  React: PluginRegisterHostApi["React"];
+  addRoute: PluginRegisterHostApi["addRoute"];
+  addTool: PluginRegisterHostApi["addTool"];
+};
+
+export function createPluginRegisterHostApi(
+  options: CreatePluginRegisterHostApiOptions,
+): PluginRegisterHostApi {
+  const addRoute = options.addRoute;
+  return {
+    React: options.React,
+    addRoute,
+    addPage: addRoute,
+    addTool: options.addTool,
+  };
+}
+
+const CONSOLE_API_BASE_STORAGE_KEY = "zhin_api_base";
+
+function resolveStoredApiBase(): string {
+  if (typeof window === "undefined") return "";
+  const stored = localStorage.getItem(CONSOLE_API_BASE_STORAGE_KEY)?.trim();
+  return stored ? stored.replace(/\/$/, "") : "";
+}
+
+function defaultEntriesUrl(): string {
+  const apiBase = resolveStoredApiBase();
+  if (apiBase) return `${apiBase}/entries`;
+  const root = DEFAULT_CONSOLE_BASE_PATH.replace(/\/$/, "");
+  return `${root ? `${root}/entries` : "/entries"}`;
+}
+
+function resolveRequestUrl(pathOrUrl: string): string {
+  if (pathOrUrl.startsWith("http://") || pathOrUrl.startsWith("https://")) return pathOrUrl;
+  if (typeof window === "undefined") return pathOrUrl;
+  const apiBase = resolveStoredApiBase();
+  const origin = apiBase || window.location.origin;
+  return new URL(pathOrUrl, `${origin}/`).href;
+}
+
+function resolvePluginImportUrl(resolvedModule: string, assetOrigin?: string): string {
+  if (resolvedModule.startsWith("http://") || resolvedModule.startsWith("https://")) return resolvedModule;
+  if (typeof window === "undefined") return resolvedModule;
+  const origin = assetOrigin?.replace(/\/$/, "") || window.location.origin;
+  return new URL(resolvedModule, `${origin}/`).href;
+}
+
+function resolveFetchInit(init?: RequestInit | (() => RequestInit)): RequestInit {
+  return typeof init === "function" ? init() : (init ?? {});
+}
+
+export async function fetchConsoleEntries(
+  options?: FetchConsoleEntriesOptions,
+): Promise<ConsoleEntriesResponse> {
+  const pathOrUrl = options?.entriesUrl ?? defaultEntriesUrl();
+  const url = resolveRequestUrl(pathOrUrl);
+  const init = resolveFetchInit(options?.fetchInit);
+  const res = await fetch(url, {
+    ...init,
+    signal: options?.signal ?? init.signal,
+  } as RequestInit);
+  if (!res.ok) throw Object.assign(new Error(`load entries failed: ${res.status}`), { status: res.status });
+  return (await res.json()) as ConsoleEntriesResponse;
+}
+
+export function getRegisterFn(mod: Record<string, unknown> | null | undefined): ConsolePluginRegister | null {
+  if (!mod) return null;
+  const r = mod["register"];
+  if (typeof r === "function") return r as ConsolePluginRegister;
+  const d = mod["default"] as Record<string, unknown> | undefined;
+  if (d && typeof d["register"] === "function") return d["register"] as ConsolePluginRegister;
+  return null;
+}
+
+export async function registerConsolePluginsFromEntries(
+  entries: ConsoleClientEntry[],
+  hostApi: PluginRegisterHostApi,
+  onEntryError?: (entry: ConsoleClientEntry, error: unknown) => void,
+  assetOrigin?: string,
+): Promise<void> {
+  if (!entries.length) return;
+  await Promise.all(
+    entries.map(async (entry) => {
+      try {
+        const specifier = resolvePluginImportUrl(entry.resolvedModule, assetOrigin);
+        const mod = (await import(/* @vite-ignore */ specifier)) as Record<string, unknown>;
+        const register = getRegisterFn(mod);
+        if (register) await register(hostApi);
+        else throw new Error(`entry "${entry.id}" has no register export`);
+      } catch (error) {
+        if (onEntryError) onEntryError(entry, error);
+        else throw error;
+      }
+    }),
+  );
+}
+
+export async function loadConsoleEntries(options: LoadConsoleEntriesOptions): Promise<void> {
+  options.beforeLoad?.();
+  let data: ConsoleEntriesResponse;
+  try {
+    data = await fetchConsoleEntries(options);
+  } catch (error) {
+    const status = typeof (error as { status?: unknown }).status === "number"
+      ? (error as { status: number }).status
+      : 0;
+    if (options.onFetchError) {
+      options.onFetchError(status);
+      return;
+    }
+    throw error;
+  }
+  if (!data.entries?.length) {
+    options.onEmpty?.();
+    return;
+  }
+  await registerConsolePluginsFromEntries(
+    data.entries,
+    options.hostApi,
+    options.onEntryError,
+    options.assetOrigin,
+  );
+}
+

package/client/console-utils/cn.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/client/console-utils/remoteApi.ts

@@ -0,0 +1,48 @@
+const TOKEN_KEY = "zhin_api_token";
+const API_BASE_KEY = "zhin_api_base";
+
+export function getApiBase(): string {
+  const stored = localStorage.getItem(API_BASE_KEY)?.trim();
+  if (stored) return stored.replace(/\/$/, "");
+  if (typeof window !== "undefined") return window.location.origin;
+  return "";
+}
+
+export function getToken(): string | null {
+  return localStorage.getItem(TOKEN_KEY);
+}
+
+export function resolveApiUrl(path: string): string {
+  const base = getApiBase();
+  const p = path.startsWith("/") ? path : `/${path}`;
+  return `${base}${p}`;
+}
+
+export function resolveWebSocketUrl(path: string): string {
+  const httpUrl = resolveApiUrl(path);
+  const url = new URL(httpUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.href;
+}
+
+/** fetch with Bearer token; relative paths resolve against {@link getApiBase}. */
+export async function apiFetch(
+  input: RequestInfo | URL,
+  init?: RequestInit,
+): Promise<Response> {
+  const token = getToken();
+  const headers = new Headers(init?.headers);
+  if (token) headers.set("Authorization", `Bearer ${token}`);
+
+  const url =
+    typeof input === "string" && input.startsWith("/")
+      ? resolveApiUrl(input)
+      : input;
+
+  const res = await fetch(url, { ...init, headers });
+  if (res.status === 401) {
+    localStorage.removeItem(TOKEN_KEY);
+    window.dispatchEvent(new CustomEvent("zhin:auth-required"));
+  }
+  return res;
+}

package/client/index.ts

@@ -1,20 +1,67 @@
-import { type ClassValue, clsx } from 'clsx'
-import { twMerge } from 'tailwind-merge'
 // Types
-export * from './types'
+export * from "./types";
 
-// 媒体 URL（含 base64://）解析，供控制台 / 沙盒等
-export { resolveMediaSrc, pickMediaRawUrl, type MediaKind } from './mediaSrc'
+// Media URL resolution
+export { resolveMediaSrc, pickMediaRawUrl, type MediaKind } from "./mediaSrc";
 
-// Redux Store
-export * from './store'
+// Console app singleton (page-manager style)
+export {
+  app,
+  type ConsoleApp,
+  type AddRouteInput,
+  type AddToolInput,
+  type ConsoleRouteRecord,
+  type RouteTreeNode,
+  type ToolTreeNode,
+  type ConsoleRouteRenderer,
+} from "./app";
 
-// Router
-export * from './router'
+// WebSocket (business data only)
+export * from "./websocket";
 
-// WebSocket
-export * from './websocket'
+// Re-export console-types
+export type {
+  PluginRegisterHostApi,
+  PluginAddRouteInput,
+  PluginAddToolInput,
+  ConsolePluginRegister,
+  ConsoleClientEntry,
+  ConsoleEntriesResponse,
+  ConsoleEntry,
+  ConsoleFileAddEntryInput,
+  RuntimeEnv,
+} from "@zhin.js/console-types";
 
-export function cn(...inputs: ClassValue[]) {
-  return twMerge(clsx(inputs))
-}
+export {
+  DEFAULT_CONSOLE_BASE_PATH,
+  CONSOLE_HOST_REACT_NAMESPACE_KEY,
+} from "@zhin.js/console-types";
+
+export { configureConsole, getRuntimeEnv } from "./runtime/index.js";
+
+export {
+  createRegistryStore,
+  useRegistry,
+  type RegistryStore,
+} from "./store/createRegistryStore.js";
+
+export { cn } from "./console-utils/cn.js";
+
+export {
+  apiFetch,
+  getApiBase,
+  getToken,
+  resolveApiUrl,
+  resolveWebSocketUrl,
+} from "./console-utils/remoteApi.js";
+
+export {
+  fetchConsoleEntries,
+  createPluginRegisterHostApi,
+  getRegisterFn,
+  loadConsoleEntries,
+  registerConsolePluginsFromEntries,
+  type CreatePluginRegisterHostApiOptions,
+  type FetchConsoleEntriesOptions,
+  type LoadConsoleEntriesOptions,
+} from "./bootstrap/loadConsoleEntries.js";

package/client/persistence/idb-store.ts

@@ -0,0 +1,76 @@
+const DB_NAME = "zhin-console";
+const DB_VERSION = 1;
+const STORE_INBOX = "inbox";
+const STORE_PENDING = "pending";
+
+export type InboxRecord = {
+  id: string;
+  adapter: string;
+  botId: string;
+  kind: "message" | "request" | "notice";
+  payload: unknown;
+  updatedAt: number;
+};
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION);
+    req.onerror = () => reject(req.error);
+    req.onsuccess = () => resolve(req.result);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(STORE_INBOX)) {
+        db.createObjectStore(STORE_INBOX, { keyPath: "id" });
+      }
+      if (!db.objectStoreNames.contains(STORE_PENDING)) {
+        db.createObjectStore(STORE_PENDING, { keyPath: "id" });
+      }
+    };
+  });
+}
+
+export async function idbPutInbox(record: InboxRecord): Promise<void> {
+  const db = await openDb();
+  await new Promise<void>((resolve, reject) => {
+    const tx = db.transaction(STORE_INBOX, "readwrite");
+    tx.objectStore(STORE_INBOX).put(record);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+  db.close();
+}
+
+export async function idbListInbox(
+  adapter: string,
+  botId: string,
+  kind: InboxRecord["kind"],
+): Promise<InboxRecord[]> {
+  const db = await openDb();
+  const all = await new Promise<InboxRecord[]>((resolve, reject) => {
+    const tx = db.transaction(STORE_INBOX, "readonly");
+    const req = tx.objectStore(STORE_INBOX).getAll();
+    req.onsuccess = () => resolve((req.result as InboxRecord[]) ?? []);
+    req.onerror = () => reject(req.error);
+  });
+  db.close();
+  return all.filter((r) => r.adapter === adapter && r.botId === botId && r.kind === kind);
+}
+
+export async function applyConsoleEvent(event: { type: string; data?: unknown }): Promise<void> {
+  const t = event.type;
+  if (t === "bot:message" || t === "bot:request" || t === "bot:notice") {
+    const data = event.data as Record<string, unknown> | undefined;
+    if (!data) return;
+    const adapter = String(data.adapter ?? "");
+    const botId = String(data.botId ?? data.bot ?? "");
+    const id = `${adapter}:${botId}:${t}:${Date.now()}`;
+    await idbPutInbox({
+      id,
+      adapter,
+      botId,
+      kind: t === "bot:message" ? "message" : t === "bot:request" ? "request" : "notice",
+      payload: data,
+      updatedAt: Date.now(),
+    });
+  }
+}

package/client/runtime/index.ts

@@ -0,0 +1,12 @@
+import type { RuntimeEnv } from "@zhin.js/console-types";
+
+let runtimeEnvFn: (() => RuntimeEnv) | null = null;
+
+export function configureConsole(options: { getRuntimeEnv: () => RuntimeEnv }) {
+  runtimeEnvFn = options.getRuntimeEnv;
+}
+
+export function getRuntimeEnv(): RuntimeEnv {
+  if (runtimeEnvFn) return runtimeEnvFn();
+  return "production";
+}

package/client/store/createRegistryStore.ts

@@ -0,0 +1,46 @@
+import * as React from "react";
+
+export type RegistryStore<T> = {
+  add(item: T): void;
+  remove(predicate: (item: T) => boolean): void;
+  getSnapshot(): readonly T[];
+  subscribe(listener: () => void): () => void;
+};
+
+export function createRegistryStore<T>(dedupeKey?: (item: T) => string): RegistryStore<T> {
+  let items: T[] = [];
+  const listeners = new Set<() => void>();
+
+  const emit = () => {
+    for (const l of listeners) l();
+  };
+
+  return {
+    add(item) {
+      if (dedupeKey) {
+        const key = dedupeKey(item);
+        if (items.some((i) => dedupeKey(i) === key)) return;
+      }
+      items = [...items, item];
+      emit();
+    },
+    remove(predicate) {
+      const next = items.filter((i) => !predicate(i));
+      if (next.length !== items.length) {
+        items = next;
+        emit();
+      }
+    },
+    getSnapshot() {
+      return items;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+export function useRegistry<T>(store: RegistryStore<T>): readonly T[] {
+  return React.useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+}