@ubean/devtools 0.6.1 → 0.6.3

package/dist/client/index.html

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="icon" href="https://img.soybeanjs.dev/logo-ubean.svg?v=202608192144" type="image/svg+xml" />
     <title>Ubean DevTools</title>
-    <script type="module" crossorigin src="/_devtools/assets/index-DJNELO3b.js"></script>
-    <link rel="stylesheet" crossorigin href="/_devtools/assets/index-CT-WdmcL.css">
+    <script type="module" crossorigin src="./assets/index-CqTOBCCw.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-CT-WdmcL.css">
   </head>
 
   <body>

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { Plugin } from "vite";
-import { ViteDevToolsNodeContext, defineRpcFunction } from "@vitejs/devtools-kit";
+import { DevframeDefinition } from "devframe/types";
 import { SharedState } from "devframe/utils/shared-state";
+import "devframe/rpc";
 //#region src/shared/env.d.ts
 export declare function maskSensitiveEnv(env: Record<string, string>): Record<string, string>;
 //#endregion
@@ -238,48 +239,48 @@ export interface DevToolsInfo {
   };
   customTabs?: DevToolsCustomTab[];
 }
-/** Read-result shape returned by `ubean:crud:read`. */
+/** Read-result shape returned by `ubean:crud-read`. */
 export interface CrudReadResult {
   success: boolean;
   content?: string;
   data?: unknown;
   error?: string;
 }
-/** Params for `ubean:ai:chat`. */
+/** Params for `ubean:ai-chat`. */
 export interface AiChatParams {
   messages: AiChatMessage[];
   apiKey?: string;
   apiBase?: string;
   model?: string;
 }
-declare module 'devframe' {
+declare module 'devframe/types' {
   interface DevframeRpcServerFunctions {
     'ubean:get-info': () => Promise<DevToolsInfo>;
     'ubean:get-env': () => Promise<Record<string, string>>;
-    'ubean:crud:create': (params: CreateCrudParams) => Promise<CrudResult>;
-    'ubean:crud:read': (params: ReadCrudParams) => Promise<CrudReadResult>;
-    'ubean:crud:update': (params: UpdateCrudParams) => Promise<CrudResult>;
-    'ubean:crud:delete': (params: DeleteCrudParams) => Promise<CrudResult>;
-    'ubean:crud:restore': (path: string) => Promise<CrudResult>;
-    'ubean:ai:tools': () => Promise<AiToolDefinition[]>;
-    'ubean:ai:chat': (params: AiChatParams) => Promise<AiChatResponse>;
-    'ubean:playground:invoke': (params: PlaygroundInvokeParams) => Promise<PlaygroundInvokeResult>;
-    'ubean:terminal:start': (params: TerminalStartParams) => Promise<{
+    'ubean:crud-create': (params: CreateCrudParams) => Promise<CrudResult>;
+    'ubean:crud-read': (params: ReadCrudParams) => Promise<CrudReadResult>;
+    'ubean:crud-update': (params: UpdateCrudParams) => Promise<CrudResult>;
+    'ubean:crud-delete': (params: DeleteCrudParams) => Promise<CrudResult>;
+    'ubean:crud-restore': (path: string) => Promise<CrudResult>;
+    'ubean:ai-tools': () => Promise<AiToolDefinition[]>;
+    'ubean:ai-chat': (params: AiChatParams) => Promise<AiChatResponse>;
+    'ubean:playground-invoke': (params: PlaygroundInvokeParams) => Promise<PlaygroundInvokeResult>;
+    'ubean:terminal-start': (params: TerminalStartParams) => Promise<{
       sessionId: string;
     }>;
-    'ubean:terminal:input': (params: {
+    'ubean:terminal-input': (params: {
       sessionId: string;
       data: string;
     }) => Promise<boolean>;
-    'ubean:terminal:resize': (params: {
+    'ubean:terminal-resize': (params: {
       sessionId: string;
       cols: number;
       rows: number;
     }) => Promise<boolean>;
-    'ubean:terminal:poll': (params: {
+    'ubean:terminal-poll': (params: {
       sessionId: string;
     }) => Promise<TerminalPollResult>;
-    'ubean:terminal:kill': (params: {
+    'ubean:terminal-kill': (params: {
       sessionId: string;
     }) => Promise<boolean>;
   }
@@ -465,6 +466,41 @@ export declare function buildDevToolsInfo(opts: BuildInfoOptions): DevToolsInfo;
 /** Initial empty state (used before scan data arrives). */
 export declare function emptyDevToolsInfo(startTime: number): DevToolsInfo;
 //#endregion
+//#region src/node/rpc/types.d.ts
+/**
+ * 本包 RPC 的命名空间。所有裸名注册后成为 `<UBEAN_RPC_NAMESPACE>:<bare-name>`。
+ */
+export declare const UBEAN_RPC_NAMESPACE = "ubean";
+/**
+ * `ubean:ai:stream` —— AI 流式响应的 shared state key。
+ *
+ * **不是** scoped key：`ctx.scope('ubean').rpc.sharedState.get('ai:stream')` 会再加一层前缀
+ * （`ubean:ai:stream` 本身已含 `:`，`qualifyName` 原样返回，因此两种写法恰好都落到这个 key）。
+ * 这里显式写全名，避免读者以为它经过 scope。
+ */
+export declare const UBEAN_AI_STREAM_STATE_KEY = "ubean:ai:stream";
+/**
+ * anchor dock 的共享 iframe 配置。
+ *
+ * `frameId` / `subTabs` 属于 **`DevframeViewIframe`**（不是 `DevframeDockDefaults`），
+ * 因此不能写在 `DevframeDefinition.dock` 里 —— 它们必须经
+ * `initHub({ devframes: [{ devframe, dock }] })`（或 `ctx.install(def, { dock })`）传入。
+ * 这里集中一处，CLI 与测试都从这里取。
+ *
+ * - `frameId`：所有视图 dock 共用一个 iframe 元素（软导航池）。
+ * - `subTabs`：客户端 host 自动挂 frame-nav 适配器，运行时发现视图清单。
+ *
+ * **不要设 `visibility: 'false'`**：它会隐藏 anchor 自己的 dock 按钮，而 iframe 只在 anchor
+ * 被激活时才挂载 —— 隐藏 anchor 就永远发现不了视图清单，外壳里只剩一个空的 dock 侧栏
+ * （实测 2026-10-11：面板整个打不开）。
+ */
+export declare const UBEAN_ANCHOR_DOCK: {
+  readonly frameId: "ubean";
+  readonly subTabs: {
+    readonly protocol: "postmessage";
+  };
+};
+//#endregion
 //#region src/node/index.d.ts
 /**
  * Options injected by the ubean dev runner so the DevTools plugin can reach
@@ -511,16 +547,38 @@ interface UbeanDevtoolsPluginOptions {
    * via sharedState — replacing the old 3s polling pattern.
    */
   registerRefresh?: (fn: () => void) => void;
+  /**
+   * Mount base for the DevTools SPA. Defaults to `/_devtools/`.
+   *
+   * devframe 的约定是每个 devframe 挂在 hub base 的 `<id>/` 下；ubean 保留
+   * `/_devtools/` 作为**用户可见**的路径（CLI banner、文档、`devtools` 命令都印它），
+   * 与 Vite 自己的 `/__devtools/` 外壳互不干扰。SPA 产物必须用相对 base 构建
+   * （见 `client/vite.config.ts` 的 `base: './'`），否则换前缀就白屏。
+   */
+  basePath?: string;
 }
 /**
- * Ubean DevTools as a Vite plugin.
+ * 构建 `@ubean/devtools` 的 devframe 定义。
  *
- * Registers a dock entry (iframe pointing at the pre-built SPA), hosts the
- * SPA's static assets, and wires up the type-safe RPC + sharedState used by
- * the SPA. This replaces the previous Hono-middleware-based transport with
- * the Vite DevTools Kit (DTK) birpc + shared-state machinery.
+ * 与旧 DTK 接线的区别：
+ * - 不再手动 `ctx.views.hostStatic` / 手写 11 个 dock entry —— hub 的 `ctx.install()`
+ *   负责服务 SPA、注册 anchor dock 与 `__connection.json`；
+ * - 不再有那段 `__connection.json` 转发 hack（hub 的 `mountConnectionMeta` 原生支持）；
+ * - RPC 走 `ctx.scope('ubean')`，裸名注册（`get-info` → wire 名 `ubean:get-info`）。
  */
-export declare function ubeanDevtoolsPlugin(options?: UbeanDevtoolsPluginOptions): Plugin;
+export declare function createUbeanDevframe(options: UbeanDevtoolsPluginOptions): DevframeDefinition;
+/**
+ * Ubean DevTools 的 Vite 插件 —— `createUbeanDevframe()` 的装配壳。
+ *
+ * 插件本身**不挂 hub**：hub 由 `@devframes/vite/hub` 的 `viteDevframeHub()` 在 dev server
+ * 里挂载，本插件只是把 devframe 定义交给它（`devframes: [createUbeanDevframe(...)]`）。
+ * 因此这个函数返回的 `Plugin` 仅用于携带 `__ubeanDevframe` 标记，便于 CLI 组装。
+ */
+interface UbeanDevtoolsPlugin extends Plugin {
+  /** 供 CLI 取出定义并挂到 hub 上。 */
+  readonly __ubeanDevframe: DevframeDefinition;
+}
+export declare function ubeanDevtoolsPlugin(options: UbeanDevtoolsPluginOptions): UbeanDevtoolsPlugin;
 //#endregion
 //#region src/node/rpc/index.d.ts
 interface RpcDeps {
@@ -534,13 +592,140 @@ interface RpcDeps {
   } | undefined;
 }
 /**
- * Returns an array of `defineRpcFunction` definitions. The return type is
- * intentionally loose (`any[]`) because the DTK `ctx.rpc.register()` accepts
- * definitions parameterized on `ViteDevToolsNodeContext`, and the exact
- * generic instantiation varies per function — the individual functions are
- * already type-checked at their definition site.
+ * 全部 RPC 定义（裸名）。`setup` 里逐个 `ctx.scope('ubean').rpc.register(fn)`。
+ */
+export declare function createAllRpcFunctions(deps: RpcDeps): ({
+  readonly name: "get-info";
+  readonly type: "query";
+  readonly setup: () => {
+    handler: () => import("devframe/utils/shared-state").ImmutableObject<DevToolsInfo>;
+  };
+} | {
+  readonly name: "get-env";
+  readonly type: "query";
+  readonly setup: () => {
+    handler: () => Record<string, string>;
+  };
+} | {
+  readonly name: "crud-create";
+  readonly type: "action";
+  readonly setup: () => {
+    handler: (params: CreateCrudParams) => Promise<CrudResult>;
+  };
+} | {
+  readonly name: "crud-read";
+  readonly type: "query";
+  readonly setup: () => {
+    handler: (params: ReadCrudParams) => Promise<{
+      success: boolean;
+      content?: string;
+      data?: unknown;
+      error?: string;
+    }>;
+  };
+} | {
+  readonly name: "crud-update";
+  readonly type: "action";
+  readonly setup: () => {
+    handler: (params: UpdateCrudParams) => Promise<CrudResult>;
+  };
+} | {
+  readonly name: "crud-delete";
+  readonly type: "action";
+  readonly setup: () => {
+    handler: (params: DeleteCrudParams) => Promise<CrudResult>;
+  };
+} | {
+  readonly name: "crud-restore";
+  readonly type: "action";
+  readonly setup: () => {
+    handler: (path: string) => Promise<CrudResult>;
+  };
+} | {
+  readonly name: "ai-tools";
+  readonly type: "query";
+  readonly setup: () => {
+    handler: () => AiToolDefinition[];
+  };
+} | {
+  readonly name: "ai-chat";
+  readonly type: "action";
+  readonly setup: () => {
+    handler: (params: {
+      messages: AiChatMessage[];
+      apiKey?: string;
+      apiBase?: string;
+      model?: string;
+    }) => Promise<AiChatResponse>;
+  };
+} | {
+  readonly name: "ai-chat-stream";
+  readonly type: "action";
+  readonly setup: () => {
+    handler: (params: {
+      messages: AiChatMessage[];
+      requestId: string;
+      apiKey?: string;
+      apiBase?: string;
+      model?: string;
+    }) => Promise<AiChatResponse>;
+  };
+} | {
+  readonly name: "playground-invoke";
+  readonly type: "action";
+  readonly setup: () => {
+    handler: (params: PlaygroundInvokeParams) => Promise<PlaygroundInvokeResult>;
+  };
+} | {
+  readonly name: "terminal-start";
+  readonly type: "action";
+  readonly setup: () => {
+    handler: (params: TerminalStartParams) => Promise<{
+      sessionId: string;
+    }>;
+  };
+} | {
+  readonly name: "terminal-input";
+  readonly type: "action";
+  readonly setup: () => {
+    handler: (params: {
+      sessionId: string;
+      data: string;
+    }) => Promise<boolean>;
+  };
+} | {
+  readonly name: "terminal-resize";
+  readonly type: "action";
+  readonly setup: () => {
+    handler: (params: {
+      sessionId: string;
+      cols: number;
+      rows: number;
+    }) => Promise<boolean>;
+  };
+} | {
+  readonly name: "terminal-poll";
+  readonly type: "query";
+  readonly setup: () => {
+    handler: (params: {
+      sessionId: string;
+    }) => Promise<TerminalPollResult>;
+  };
+} | {
+  readonly name: "terminal-kill";
+  readonly type: "action";
+  readonly setup: () => {
+    handler: (params: {
+      sessionId: string;
+    }) => Promise<boolean>;
+  };
+})[];
+/**
+ * 全部 RPC 定义的元组类型（每个子模块返回 `as const` 元组，故这里是精确的窄元组）。
+ * 客户端侧的 wire 签名由 `RpcDefinitionsToFunctionsWithNamespace<'ubean', UbeanRpcFunctions>`
+ * 推导。
  */
-export declare function createAllRpcFunctions(deps: RpcDeps): any[];
+type UbeanRpcFunctions = ReturnType<typeof createAllRpcFunctions>;
 //#endregion
 //#region src/define-tab.d.ts
 /**
@@ -561,4 +746,4 @@ export declare function defineDevToolsTab(tab: DevToolsTabDefinition): DevToolsT
 export declare function getCustomTabs(): DevToolsTabDefinition[];
 export declare function clearCustomTabs(): void;
 //#endregion
-export { type AiChatMessage, type AiChatResponse, type AiToolDefinition, type DevToolsAiServer, type DevToolsConfigMeta, type DevToolsCrudServer, type DevToolsHooks, type DevToolsHooksInstance, type DevToolsTabDefinition, type ScanResultLike, type TerminalPollResult, type TerminalServer, type TerminalStartParams, type UbeanDevtoolsPluginOptions, type ViteDevToolsNodeContext, defineRpcFunction };
+export type { AiChatMessage, AiChatResponse, AiToolDefinition, DevToolsAiServer, DevToolsConfigMeta, DevToolsCrudServer, DevToolsHooks, DevToolsHooksInstance, DevToolsTabDefinition, RpcDeps, ScanResultLike, TerminalPollResult, TerminalServer, TerminalStartParams, UbeanDevtoolsPlugin, UbeanDevtoolsPluginOptions, UbeanRpcFunctions };