@talex-touch/utils 1.0.21 → 1.0.22

package/package.json

@@ -5,7 +5,7 @@
   "module": "./index.ts",
   "license": "MPL-2.0",
   "private": false,
-  "version": "1.0.21",
+  "version": "1.0.22",
   "scripts": {
     "publish": "npm publish --access public"
   },

package/plugin/index.ts

@@ -377,4 +377,5 @@ export interface IManifest {
 export type { LogLevel, LogItem, LogDataType, IPluginLogger } from './log/types'
 export * from './sdk/index'
 export * from './providers'
+export * from './install'
 export * from './risk'

package/plugin/install.ts

@@ -0,0 +1,43 @@
+export type PluginInstallTaskStage =
+  | 'queued'
+  | 'downloading'
+  | 'awaiting-confirmation'
+  | 'installing'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+export interface PluginInstallProgressEvent {
+  taskId: string
+  stage: PluginInstallTaskStage
+  progress?: number
+  message?: string
+  error?: string
+  /** 安装源标识，例如下载 URL。 */
+  source?: string
+  /** 官方插件标记。 */
+  official?: boolean
+  /** 插件唯一标识或名称（由客户端提供）。 */
+  pluginId?: string
+  pluginName?: string
+  /** 队列中的剩余任务数量（包含当前任务）。 */
+  remaining?: number
+  /** 当前任务在队列中的位置（0 表示正在处理）。 */
+  position?: number
+}
+
+export interface PluginInstallConfirmRequest {
+  taskId: string
+  pluginName?: string
+  pluginId?: string
+  source?: string
+  official?: boolean
+}
+
+export type PluginInstallConfirmDecision = 'accept' | 'reject'
+
+export interface PluginInstallConfirmResponse {
+  taskId: string
+  decision: PluginInstallConfirmDecision
+  reason?: string
+}

package/plugin/node/logger-manager.ts

@@ -12,6 +12,7 @@ export class PluginLoggerManager {
   private readonly pluginLogDir: string
   private readonly sessionLogPath: string
   private readonly pluginInfoPath: string
+  private readonly sessionStart: string
   private buffer: LogItem[] = []
   private flushInterval: NodeJS.Timeout
   private onLogAppend?: (log: LogItem) => void
@@ -25,15 +26,15 @@ export class PluginLoggerManager {
   constructor(baseDir: string, pluginInfo: ITouchPlugin, onLogAppend?: (log: LogItem) => void) {
     this.pluginInfo = pluginInfo
     this.onLogAppend = onLogAppend
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+    this.sessionStart = new Date().toISOString()
+    const timestamp = this.sessionStart.replace(/[:.]/g, '-')
     const sessionFolder = `${timestamp}_${pluginInfo.name.replace(/[^a-zA-Z0-9-_]/g, '_')}`
 
     this.pluginLogDir = path.resolve(baseDir, 'logs', sessionFolder)
     this.sessionLogPath = path.resolve(this.pluginLogDir, 'session.log')
     this.pluginInfoPath = path.resolve(this.pluginLogDir, 'touch-plugin.info')
 
-    this.ensureDirectory()
-    this.createPluginInfoFile()
+    this.ensureLogEnvironment(true)
     this.flushInterval = setInterval(() => this.flush(), 5000)
   }
 
@@ -52,8 +53,17 @@ export class PluginLoggerManager {
   flush(): void {
     if (this.buffer.length === 0) return
     const lines = this.buffer.map((item) => structuredStrictStringify(item)).join('\n') + '\n'
-    fs.appendFileSync(this.sessionLogPath, lines)
-    this.buffer = []
+    try {
+      this.ensureLogEnvironment()
+      fs.appendFileSync(this.sessionLogPath, lines)
+      this.buffer = []
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') throw error
+      // Directory or file was removed; rebuild and retry once.
+      this.ensureLogEnvironment(true)
+      fs.appendFileSync(this.sessionLogPath, lines)
+      this.buffer = []
+    }
   }
 
   /**
@@ -83,12 +93,12 @@ export class PluginLoggerManager {
   /**
    * Creates the touch-plugin.info file with plugin information.
    */
-  private createPluginInfoFile(): void {
+  private writePluginInfoFile(): void {
     const pluginInfo = {
       name: this.pluginInfo.name,
       version: this.pluginInfo.version,
       description: this.pluginInfo.desc,
-      sessionStart: new Date().toISOString(),
+      sessionStart: this.sessionStart,
       icon: this.pluginInfo.icon,
       platforms: this.pluginInfo.platforms,
       status: this.pluginInfo.status,
@@ -103,11 +113,19 @@ export class PluginLoggerManager {
   }
 
   /**
-   * Ensures the log directory exists.
+   * Ensures the log directory and related files exist.
    */
-  private ensureDirectory(): void {
+  private ensureLogEnvironment(forceInfo = false): void {
     if (!fs.existsSync(this.pluginLogDir)) {
       fs.mkdirSync(this.pluginLogDir, { recursive: true })
     }
+
+    if (!fs.existsSync(this.sessionLogPath)) {
+      fs.writeFileSync(this.sessionLogPath, '')
+    }
+
+    if (forceInfo || !fs.existsSync(this.pluginInfoPath)) {
+      this.writePluginInfoFile()
+    }
   }
 }

package/plugin/providers/types.ts

@@ -17,6 +17,8 @@ export interface PluginInstallRequest {
   hintType?: PluginProviderType
   /** 可选元数据，在调用链中透传。 */
   metadata?: Record<string, unknown>
+  /** 客户端附加信息，仅用于 UI 状态同步。 */
+  clientMetadata?: Record<string, unknown>
 }
 
 export interface PluginProviderContext {

package/plugin/sdk/channel.ts

@@ -0,0 +1,48 @@
+import type { ITouchClientChannel } from '@talex-touch/utils/channel';
+import { genChannel } from '../channel';
+import type { IPluginRendererChannel, PluginChannelHandler } from './types';
+
+const ensureClientChannel = (): ITouchClientChannel => genChannel();
+
+export function createPluginRendererChannel(): IPluginRendererChannel {
+  const client = ensureClientChannel();
+
+  return {
+    send(eventName, payload) {
+      return client.send(eventName, payload);
+    },
+
+    sendSync(eventName, payload) {
+      return client.sendSync(eventName, payload);
+    },
+
+    on(eventName, handler) {
+      return client.regChannel(eventName, handler);
+    },
+
+    once(eventName, handler) {
+      let dispose: () => void = () => void 0;
+      const wrapped: PluginChannelHandler = (event) => {
+        dispose();
+        handler(event);
+      };
+
+      dispose = client.regChannel(eventName, wrapped);
+      return dispose;
+    },
+
+    get raw() {
+      return client;
+    }
+  };
+}
+
+let cachedRendererChannel: IPluginRendererChannel | null = null;
+
+export function usePluginRendererChannel(): IPluginRendererChannel {
+  if (!cachedRendererChannel) {
+    cachedRendererChannel = createPluginRendererChannel();
+  }
+
+  return cachedRendererChannel;
+}

package/plugin/sdk/clipboard.ts

@@ -0,0 +1,56 @@
+import type { PluginClipboardHistoryResponse, PluginClipboardItem } from './types'
+
+const ensurePluginChannel = () => {
+  const channel = (window as any)?.$channel
+  if (!channel) {
+    throw new Error('[Plugin SDK] Clipboard channel requires plugin renderer context with $channel available.')
+  }
+  return channel
+}
+
+export interface ClipboardHistoryOptions {
+  page?: number
+}
+
+export interface ClipboardFavoriteOptions {
+  id: number
+  isFavorite: boolean
+}
+
+export interface ClipboardDeleteOptions {
+  id: number
+}
+
+export function useClipboardHistory() {
+  const channel = ensurePluginChannel()
+
+  return {
+    async getLatest(): Promise<PluginClipboardItem | null> {
+      return channel.send('clipboard:get-latest')
+    },
+
+    async getHistory(options: ClipboardHistoryOptions = {}): Promise<PluginClipboardHistoryResponse> {
+      const { page = 1 } = options
+      return channel.send('clipboard:get-history', { page })
+    },
+
+    async setFavorite(options: ClipboardFavoriteOptions): Promise<void> {
+      await channel.send('clipboard:set-favorite', options)
+    },
+
+    async deleteItem(options: ClipboardDeleteOptions): Promise<void> {
+      await channel.send('clipboard:delete-item', options)
+    },
+
+    async clearHistory(): Promise<void> {
+      await channel.send('clipboard:clear-history')
+    },
+
+    onDidChange(callback: (item: PluginClipboardItem) => void): () => void {
+      return channel.regChannel('core-box:clipboard-change', ({ data }) => {
+        const item = (data && 'item' in data ? data.item : data) as PluginClipboardItem
+        callback(item)
+      })
+    }
+  }
+}

package/plugin/sdk/hooks/bridge.ts

@@ -10,6 +10,7 @@ export type BridgeHook<T = any> = (data: T) => void
 
 const __hooks: Record<BridgeEvent, Array<BridgeHook>> = {
   [BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE]: [],
+  [BridgeEventForCoreBox.CORE_BOX_CLIPBOARD_CHANGE]: []
 }
 
 /**
@@ -66,3 +67,5 @@ export const createBridgeHook = <T>(type: BridgeEvent) => (hook: BridgeHook<T>)
  * @param data The input change data (string).
  */
 export const onCoreBoxInputChange = createBridgeHook<{ query: string }>(BridgeEventForCoreBox.CORE_BOX_INPUT_CHANGE)
+
+export const onCoreBoxClipboardChange = createBridgeHook<{ item: any }>(BridgeEventForCoreBox.CORE_BOX_CLIPBOARD_CHANGE)

package/plugin/sdk/index.ts

@@ -17,4 +17,6 @@ export * from './window/index'
 export * from './hooks/index'
 export * from './service/index'
 
-export * from './storage'
+export * from './channel'
+export * from './clipboard'
+export * from './storage'

package/plugin/sdk/types.ts

@@ -4,6 +4,109 @@
  * @version 1.0.0
  */
 
+import type { ITouchChannel, ITouchClientChannel, StandardChannelData } from '@talex-touch/utils/channel';
+
+/**
+ * Handler signature for plugin channel events.
+ */
+export type PluginChannelHandler = (event: StandardChannelData) => any;
+
+/**
+ * Bridge exposed to plugin backends for channel-based communication.
+ */
+export interface IPluginChannelBridge {
+  /**
+   * Sends a payload to the main renderer process.
+   * @param eventName - Channel event name.
+   * @param payload - Optional data payload.
+   */
+  sendToMain<T = any>(eventName: string, payload?: any): Promise<T>;
+
+  /**
+   * Sends a payload to this plugin's renderer view.
+   * @param eventName - Channel event name.
+   * @param payload - Optional data payload.
+   */
+  sendToRenderer<T = any>(eventName: string, payload?: any): Promise<T>;
+
+  /**
+   * Registers a handler for main renderer messages.
+   * @param eventName - Channel event name to listen for.
+   * @param handler - Handler invoked with the raw channel event.
+   * @returns Unsubscribe function.
+   */
+  onMain(eventName: string, handler: PluginChannelHandler): () => void;
+
+  /**
+   * Registers a handler for renderer-originated messages scoped to this plugin.
+   * @param eventName - Channel event name to listen for.
+   * @param handler - Handler invoked with the raw channel event.
+   * @returns Unsubscribe function.
+   */
+  onRenderer(eventName: string, handler: PluginChannelHandler): () => void;
+
+  /**
+   * Access to the underlying channel implementation for advanced scenarios.
+   */
+  readonly raw: ITouchChannel;
+}
+
+/**
+ * Renderer-side helper for plugin webviews to interact with the bridge channel.
+ */
+export interface IPluginRendererChannel {
+  /**
+   * Sends a message asynchronously and resolves with the reply payload.
+   */
+  send<T = any>(eventName: string, payload?: any): Promise<T>;
+
+  /**
+   * Sends a message synchronously and returns the reply payload.
+   */
+  sendSync<T = any>(eventName: string, payload?: any): T;
+
+  /**
+   * Registers a handler for renderer channel events.
+   * @returns Unsubscribe function.
+   */
+  on(eventName: string, handler: PluginChannelHandler): () => void;
+
+  /**
+   * Registers a one-off handler for a renderer channel event.
+   * @returns Unsubscribe function (no-op after invocation).
+   */
+  once(eventName: string, handler: PluginChannelHandler): () => void;
+
+  /**
+   * Provides access to the raw client channel.
+   */
+  readonly raw: ITouchClientChannel;
+}
+
+/**
+ * Clipboard history item shared with plugin renderers.
+ */
+export interface PluginClipboardItem {
+  id?: number
+  type: 'text' | 'image' | 'files'
+  content: string
+  thumbnail?: string | null
+  rawContent?: string | null
+  sourceApp?: string | null
+  timestamp?: string | number | Date | null
+  isFavorite?: boolean | null
+}
+
+/**
+ * Clipboard history pagination response structure.
+ */
+export interface PluginClipboardHistoryResponse {
+  history: PluginClipboardItem[]
+  total: number
+  page: number
+  pageSize: number
+}
+
 /**
  * Plugin utilities interface providing core functionality for plugin development
  *
@@ -28,6 +131,12 @@ export interface IPluginUtils {
    */
   clipboard: IClipboardManager;
 
+  /**
+   * Channel bridge for communicating with renderer and main processes
+   * @see {@link IPluginChannelBridge}
+   */
+  channel: IPluginChannelBridge;
+
   /**
    * Search result manager for handling search operations
    * @see {@link ISearchManager}