@ubean/devtools 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -0,0 +1,561 @@
+import { Plugin } from "vite";
+import { ViteDevToolsNodeContext, defineRpcFunction } from "@vitejs/devtools-kit";
+import { SharedState } from "devframe/utils/shared-state";
+//#region src/shared/env.d.ts
+declare function maskSensitiveEnv(env: Record<string, string>): Record<string, string>;
+//#endregion
+//#region src/server/hooks.d.ts
+interface DevToolsHooks {
+  beforeCreate: (ctx: CrudHookContext) => void | Promise<void>;
+  afterCreate: (ctx: CrudHookContext) => void | Promise<void>;
+  beforeUpdate: (ctx: CrudHookContext) => void | Promise<void>;
+  afterUpdate: (ctx: CrudHookContext) => void | Promise<void>;
+  beforeDelete: (ctx: CrudHookContext) => void | Promise<void>;
+  afterDelete: (ctx: CrudHookContext) => void | Promise<void>;
+}
+declare function createDevToolsHooks(): {
+  registerHook: (type: CrudHookType, handler: CrudHookHandler) => void;
+  runHook: (type: CrudHookType, ctx: CrudHookContext) => Promise<void>;
+  removeHook: (type: CrudHookType, handler: CrudHookHandler) => void;
+  removeAllHooks: () => void;
+  hook: <NameT extends import("hookable").HookKeys<DevToolsHooks>>(name: NameT, function_: DevToolsHooks[NameT] extends import("hookable").HookCallback ? DevToolsHooks[NameT] : never, options?: {
+    allowDeprecated?: boolean;
+  }) => () => void;
+  callHook: <NameT extends import("hookable").HookKeys<DevToolsHooks>>(name: NameT, ...args: Parameters<DevToolsHooks[NameT] extends import("hookable").HookCallback ? DevToolsHooks[NameT] : never>) => Promise<any> | void;
+};
+type DevToolsHooksInstance = ReturnType<typeof createDevToolsHooks>;
+//#endregion
+//#region src/server/crud.d.ts
+interface CrudServerOptions {
+  cwd: string;
+  hooks?: DevToolsHooksInstance;
+  getEnv?: () => Record<string, string>;
+  setEnv?: (env: Record<string, string>) => void;
+  getConfig?: () => Record<string, unknown>;
+  onFileChange?: () => void | Promise<void>;
+  scaffoldOps?: DevToolsScaffoldOps;
+}
+declare function createCrudServer(options: CrudServerOptions): {
+  create: (params: CreateCrudParams) => Promise<CrudResult>;
+  read: (params: ReadCrudParams) => Promise<{
+    success: boolean;
+    content?: string;
+    data?: unknown;
+    error?: string;
+  }>;
+  update: (params: UpdateCrudParams) => Promise<CrudResult>;
+  delete: (params: DeleteCrudParams) => Promise<CrudResult>;
+  restore: (path: string) => Promise<CrudResult>;
+};
+type DevToolsCrudServer = ReturnType<typeof createCrudServer>;
+//#endregion
+//#region src/server/ai.d.ts
+interface AiToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+interface AiToolResult {
+  toolCallId: string;
+  result?: unknown;
+  error?: string;
+}
+interface AiChatMessage {
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string;
+  toolCalls?: AiToolCall[];
+  toolCallId?: string;
+  toolResults?: AiToolResult[];
+  timestamp: number;
+}
+interface AiToolDefinition {
+  name: string;
+  description: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, AiToolParam>;
+    required?: string[];
+  };
+}
+interface AiToolParam {
+  type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  description: string;
+  enum?: string[];
+  items?: {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+  };
+}
+interface AiChatOptions {
+  messages: AiChatMessage[];
+  model?: string;
+  apiKey?: string;
+  apiBase?: string;
+  /** When provided, the server streams text deltas via this callback. */
+  requestId?: string;
+}
+interface AiChatResponse {
+  message: AiChatMessage;
+  toolResults?: AiToolResult[];
+}
+/** A chunk pushed to the client during streaming. */
+interface AiStreamChunk {
+  requestId: string;
+  /** Accumulated text so far (not a delta). */
+  text: string;
+  done: boolean;
+  toolCalls?: AiToolCall[];
+  toolResults?: AiToolResult[];
+  error?: string;
+}
+declare function createAiServer(crud: DevToolsCrudServer, getInfo: () => DevToolsInfo, onStreamChunk?: (chunk: AiStreamChunk) => void): {
+  getToolDefinitions: () => AiToolDefinition[];
+  executeToolCall: (call: AiToolCall) => Promise<AiToolResult>;
+  chat: (options: AiChatOptions) => Promise<AiChatResponse>;
+  parseCommand: (input: string) => {
+    toolCalls?: AiToolCall[];
+    response?: string;
+  } | null;
+  formatToolResult: (name: string, result: unknown) => string;
+};
+type DevToolsAiServer = ReturnType<typeof createAiServer>;
+//#endregion
+//#region src/node/rpc/playground.d.ts
+interface PlaygroundInvokeParams {
+  method: string;
+  path: string;
+  body?: unknown;
+  headers?: Record<string, string>;
+}
+interface PlaygroundInvokeResult {
+  status: number;
+  statusText: string;
+  body: unknown;
+  headers: Record<string, string>;
+}
+//#endregion
+//#region src/server/terminal.d.ts
+interface TerminalStartParams {
+  cwd: string;
+  cols?: number;
+  rows?: number;
+  /** Shell command; defaults to the user's default shell. */
+  shell?: string;
+}
+interface TerminalPollResult {
+  data: string;
+  exited: boolean;
+  exitCode: number | null;
+}
+declare function createTerminalServer(): {
+  start: (params: TerminalStartParams) => {
+    sessionId: string;
+  };
+  input: (sessionId: string, data: string) => boolean;
+  resize: (sessionId: string, cols: number, rows: number) => boolean;
+  poll: (sessionId: string) => TerminalPollResult;
+  kill: (sessionId: string) => boolean;
+  killAll: () => void;
+};
+type TerminalServer = ReturnType<typeof createTerminalServer>;
+//#endregion
+//#region src/types.d.ts
+interface DevToolsOptions {
+  enabled?: boolean;
+  port?: number;
+  host?: string;
+  ai?: {
+    apiKey?: string;
+    apiBase?: string;
+    model?: string;
+  };
+}
+interface DevToolsRouteInfo {
+  method: string;
+  path: string;
+  filePath?: string;
+}
+interface DevToolsPageInfo {
+  path: string;
+  name?: string;
+  filePath?: string;
+  layout?: string;
+}
+interface DevToolsMiddlewareInfo {
+  path: string;
+  filePath?: string;
+  global: boolean;
+}
+interface DevToolsCronInfo {
+  name: string;
+  schedule?: string;
+  filePath?: string;
+}
+interface DevToolsLayoutInfo {
+  name: string;
+  path: string;
+  filePath?: string;
+  isDefault: boolean;
+}
+interface DevToolsCustomTab {
+  id: string;
+  label: string;
+  icon?: string;
+  src: string;
+  sandbox?: string[];
+}
+interface DevToolsInfo {
+  version: string;
+  startTime: number;
+  config: Record<string, unknown>;
+  env?: Record<string, string>;
+  pages: number;
+  apiRoutes: number;
+  middleware: number;
+  layouts?: number;
+  crons?: number;
+  presets?: string[];
+  routes?: DevToolsRouteInfo[];
+  pagesList?: DevToolsPageInfo[];
+  middlewaresList?: DevToolsMiddlewareInfo[];
+  layoutsList?: DevToolsLayoutInfo[];
+  cronsList?: DevToolsCronInfo[];
+  openAPI?: {
+    enabled: boolean;
+    scalarPath?: string;
+    openAPIPath?: string;
+  };
+  database?: {
+    drizzleStudioAvailable?: boolean;
+    studioUrl?: string;
+  };
+  ai?: {
+    enabled: boolean;
+    provider?: string;
+    model?: string;
+  };
+  customTabs?: DevToolsCustomTab[];
+}
+/** Read-result shape returned by `ubean:crud:read`. */
+interface CrudReadResult {
+  success: boolean;
+  content?: string;
+  data?: unknown;
+  error?: string;
+}
+/** Params for `ubean:ai:chat`. */
+interface AiChatParams {
+  messages: AiChatMessage[];
+  apiKey?: string;
+  apiBase?: string;
+  model?: string;
+}
+declare module 'devframe' {
+  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<{
+      sessionId: string;
+    }>;
+    'ubean:terminal:input': (params: {
+      sessionId: string;
+      data: string;
+    }) => Promise<boolean>;
+    'ubean:terminal:resize': (params: {
+      sessionId: string;
+      cols: number;
+      rows: number;
+    }) => Promise<boolean>;
+    'ubean:terminal:poll': (params: {
+      sessionId: string;
+    }) => Promise<TerminalPollResult>;
+    'ubean:terminal:kill': (params: {
+      sessionId: string;
+    }) => Promise<boolean>;
+  }
+  interface DevframeRpcSharedStates {
+    'ubean:info': DevToolsInfo;
+  }
+}
+type RpcHandler = (params: unknown) => unknown | Promise<unknown>;
+interface DevToolsServer {
+  rpcHandlers: Map<string, RpcHandler>;
+  registerHandler: (name: string, handler: RpcHandler) => void;
+  getInfo: () => DevToolsInfo;
+}
+interface RpcRequest {
+  id: string;
+  method: string;
+  params?: unknown;
+}
+interface RpcResponse<T = unknown> {
+  id: string;
+  result?: T;
+  error?: string;
+}
+interface DevToolsTab {
+  id: string;
+  label: string;
+  icon?: string;
+}
+type CrudResourceType = 'page' | 'api' | 'layout' | 'middleware' | 'reuse' | 'cron' | 'plugin';
+interface CrudResult {
+  success: boolean;
+  created?: string[];
+  deleted?: string[];
+  restored?: string[];
+  updated?: string[];
+  skipped?: string[];
+  errors?: string[];
+}
+interface CreateCrudParams {
+  type: CrudResourceType;
+  path: string;
+  method?: string;
+  schedule?: string;
+  content?: string;
+  force?: boolean;
+}
+interface ReadCrudParams {
+  type: CrudResourceType | 'env' | 'config';
+  path?: string;
+}
+interface UpdateCrudParams {
+  type: CrudResourceType | 'env' | 'config';
+  path?: string;
+  key?: string;
+  content?: string;
+  value?: string;
+}
+interface DeleteCrudParams {
+  type: CrudResourceType | 'env';
+  path?: string;
+  key?: string;
+  force?: boolean;
+}
+type CrudHookType = 'beforeCreate' | 'afterCreate' | 'beforeUpdate' | 'afterUpdate' | 'beforeDelete' | 'afterDelete';
+interface CrudHookContext {
+  type: CrudResourceType | 'env' | 'config';
+  path?: string;
+  key?: string;
+  content?: string;
+  value?: string;
+}
+type CrudHookHandler = (ctx: CrudHookContext) => void | Promise<void>;
+type DevToolsScaffoldType = 'page' | 'api' | 'layout' | 'middleware' | 'reuse';
+interface ScaffoldResult {
+  created: string[];
+  deleted: string[];
+  restored: string[];
+  skipped: string[];
+  errors: string[];
+}
+interface ScaffoldOptions {
+  cwd?: string;
+  type: DevToolsScaffoldType;
+  path: string;
+  method?: string;
+  force?: boolean;
+  dry?: boolean;
+  baseDir?: string;
+}
+interface DevToolsFsOps {
+  exists: (path: string) => Promise<boolean>;
+  readFile: (path: string, enc?: BufferEncoding) => Promise<string>;
+  writeFile: (path: string, content: string, enc?: BufferEncoding) => Promise<void>;
+  remove: (path: string) => Promise<void>;
+  copyFile: (src: string, dest: string) => Promise<void>;
+  createBackup: (path: string, opts?: {
+    backupSuffix?: string;
+    removeOriginal?: boolean;
+  }) => Promise<string | null>;
+  removeBackup: (path: string, opts?: {
+    backupSuffix?: string;
+  }) => Promise<void>;
+}
+interface DevToolsScaffoldOps {
+  createFsOps: (cwd: string) => DevToolsFsOps;
+  scaffold: (opts: ScaffoldOptions) => Promise<ScaffoldResult>;
+  deleteScaffold: (opts: ScaffoldOptions) => Promise<ScaffoldResult>;
+  recoverScaffold: (opts: ScaffoldOptions) => Promise<ScaffoldResult>;
+}
+//#endregion
+//#region src/node/state.d.ts
+/** SharedState key for the ubean devtools info snapshot. */
+declare const UBEAN_INFO_STATE_KEY = "ubean:info";
+/**
+ * Structural shape of the scan data passed by `dev.ts`. Defined here
+ * (rather than importing ubean's `ScanResult`) so `@ubean/devtools`
+ * has no static dependency on `ubean`.
+ */
+interface ScanResultLike {
+  apiRoutes: Array<{
+    method?: string;
+    route: string;
+    relativePath: string;
+    fullPath: string;
+  }>;
+  pages: Array<{
+    route: string;
+    name: string;
+    relativePath: string;
+    fullPath: string;
+    isReuse: boolean;
+    layout?: string | false;
+  }>;
+  middlewares: Array<{
+    global: boolean;
+    relativePath: string;
+    fullPath: string;
+  }>;
+  layouts: Array<{
+    name: string;
+    path: string;
+    relativePath: string;
+    fullPath: string;
+    isDefault: boolean;
+  }>;
+  crons: Array<{
+    name: string;
+    relativePath: string;
+    fullPath: string;
+  }>;
+}
+/** Config metadata passed by `dev.ts` for the DevToolsInfo.config field. */
+interface DevToolsConfigMeta {
+  preset: string;
+  rootDir: string;
+  srcDir: string;
+  openAPI?: {
+    enabled: boolean;
+    scalarPath?: string;
+    openAPIPath?: string;
+  };
+  database?: {
+    drizzleStudioAvailable?: boolean;
+    studioUrl?: string;
+  };
+  /** Directory configuration for project structure (e.g. { routes: 'routes', pages: 'pages' }). */
+  dir?: Record<string, string>;
+}
+interface BuildInfoOptions {
+  scan: ScanResultLike | null;
+  configMeta: DevToolsConfigMeta | null;
+  customTabs: DevToolsCustomTab[];
+  ai?: {
+    apiKey?: string;
+    apiBase?: string;
+    model?: string;
+  };
+  startTime: number;
+  envData: Record<string, string>;
+}
+/** Build a fresh `DevToolsInfo` from scan + config metadata. */
+declare function buildDevToolsInfo(opts: BuildInfoOptions): DevToolsInfo;
+/** Initial empty state (used before scan data arrives). */
+declare function emptyDevToolsInfo(startTime: number): DevToolsInfo;
+//#endregion
+//#region src/node/index.d.ts
+/**
+ * Options injected by the ubean dev runner so the DevTools plugin can reach
+ * Hono-runtime data (scanned routes/pages, the Hono app for in-process
+ * playground forwarding) without `@ubean/devtools` statically depending on
+ * `ubean`.
+ */
+interface UbeanDevtoolsPluginOptions {
+  /** Project root directory (used by the CRUD server for file scaffolding). */
+  getCwd: () => string;
+  /** Accessor for the live Hono app — used by the playground RPC to forward
+   *  HTTP requests in-process without a network round-trip. */
+  getApp?: () => {
+    fetch: (req: Request) => Response | Promise<Response>;
+  } | undefined;
+  /** Accessor for the latest project scan result (routes/pages/middleware/...). */
+  getScanResult?: () => ScanResultLike | null;
+  /** Accessor for resolved config metadata shown in the Overview tab. */
+  getConfigMeta?: () => DevToolsConfigMeta | null;
+  /** Accessor for user-defined custom tabs (from `defineDevToolsTab`). */
+  getCustomTabs?: () => DevToolsCustomTab[];
+  /**
+   * Scaffold operations injected by ubean so @ubean/devtools never has a
+   * hard runtime dependency on ubean. Provides fs ops + scaffold/delete/recover
+   * functions used by the CRUD server for file creation/deletion.
+   */
+  scaffoldOps?: DevToolsScaffoldOps;
+  /** AI provider configuration forwarded to the AI server. */
+  ai?: {
+    apiKey?: string;
+    apiBase?: string;
+    model?: string;
+  };
+  /**
+   * Trigger an immediate project rescan + app reload. Called by the CRUD
+   * server after file create/update/delete so the DevTools list updates
+   * without waiting for the file watcher's debounce.
+   */
+  triggerRescan?: () => void | Promise<void>;
+  /**
+   * The dev runner registers a refresh callback here. Whenever the app is
+   * rebuilt (file change), the runner invokes it so the plugin can rebuild
+   * `DevToolsInfo` from the latest scan data and push patches to clients
+   * via sharedState — replacing the old 3s polling pattern.
+   */
+  registerRefresh?: (fn: () => void) => void;
+}
+/**
+ * Ubean DevTools as a Vite plugin.
+ *
+ * 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.
+ */
+declare function ubeanDevtoolsPlugin(options?: UbeanDevtoolsPluginOptions): Plugin;
+//#endregion
+//#region src/node/rpc/index.d.ts
+interface RpcDeps {
+  state: SharedState<DevToolsInfo>;
+  getEnvData: () => Record<string, string>;
+  crud: DevToolsCrudServer;
+  ai: DevToolsAiServer;
+  terminal: TerminalServer;
+  getApp?: () => {
+    fetch: (req: Request) => Response | Promise<Response>;
+  } | 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.
+ */
+declare function createAllRpcFunctions(deps: RpcDeps): any[];
+//#endregion
+//#region src/define-tab.d.ts
+/**
+ * Custom DevTools tab registration API.
+ *
+ * Migrated from `packages/ubean/src/core/devtools/define-tab.ts` during
+ * Phase 7 aggregator switch. Provides a global registry for user-defined
+ * DevTools tabs that are surfaced in the DevTools SPA via `DevToolsInfo.customTabs`.
+ */
+interface DevToolsTabDefinition {
+  id: string;
+  label: string;
+  icon?: string;
+  src: string;
+  sandbox?: string[];
+}
+declare function defineDevToolsTab(tab: DevToolsTabDefinition): DevToolsTabDefinition;
+declare function getCustomTabs(): DevToolsTabDefinition[];
+declare function clearCustomTabs(): void;
+//#endregion
+export { type AiChatMessage, AiChatParams, type AiChatResponse, type AiToolDefinition, CreateCrudParams, CrudHookContext, CrudHookHandler, CrudHookType, CrudReadResult, CrudResourceType, CrudResult, DeleteCrudParams, type DevToolsAiServer, type DevToolsConfigMeta, DevToolsCronInfo, type DevToolsCrudServer, DevToolsCustomTab, DevToolsFsOps, type DevToolsHooks, type DevToolsHooksInstance, DevToolsInfo, DevToolsLayoutInfo, DevToolsMiddlewareInfo, DevToolsOptions, DevToolsPageInfo, DevToolsRouteInfo, DevToolsScaffoldOps, DevToolsScaffoldType, DevToolsServer, DevToolsTab, type DevToolsTabDefinition, ReadCrudParams, RpcHandler, RpcRequest, RpcResponse, ScaffoldOptions, ScaffoldResult, type ScanResultLike, type TerminalPollResult, type TerminalServer, type TerminalStartParams, UBEAN_INFO_STATE_KEY, type UbeanDevtoolsPluginOptions, UpdateCrudParams, type ViteDevToolsNodeContext, buildDevToolsInfo, clearCustomTabs, createAiServer, createAllRpcFunctions, createCrudServer, createDevToolsHooks, createTerminalServer, defineDevToolsTab, defineRpcFunction, emptyDevToolsInfo, getCustomTabs, maskSensitiveEnv, ubeanDevtoolsPlugin };