@talex-touch/utils 1.0.18 → 1.0.20

package/plugin/channel.ts

@@ -1,6 +1,4 @@
-// import { ipcRenderer } from 'electron';
-// const { ipcRenderer, IpcMainEvent } = require("electron");
-import { IpcRenderer, type IpcRendererEvent } from "electron";
+import type { IpcRenderer, IpcRendererEvent } from 'electron'
 import {
   ChannelType,
   DataCode,
@@ -10,14 +8,41 @@ import {
   StandardChannelData,
 } from "../channel";
 
-let ipcRenderer: IpcRenderer
+let cachedIpcRenderer: IpcRenderer | null = null
 
-if (typeof window === 'undefined') {
-  ipcRenderer = require('electron').ipcRenderer
-} else {
-  ipcRenderer = window.electron.ipcRenderer as unknown as IpcRenderer
+// 使用惰性解析避免在打包阶段静态引入 electron
+const resolveIpcRenderer = (): IpcRenderer | null => {
+  if (typeof window !== 'undefined') {
+    const bridge = (window as any)?.electron
+    if (bridge?.ipcRenderer) return bridge.ipcRenderer as IpcRenderer
+  }
+
+  try {
+    const electron = (globalThis as any)?.electron ?? (eval('require') as any)?.('electron')
+    if (electron?.ipcRenderer) return electron.ipcRenderer as IpcRenderer
+  } catch (error) {
+    // ignore – will throw below if no ipcRenderer is resolved
+  }
+
+  return null
+}
+
+const ensureIpcRenderer = (): IpcRenderer => {
+  if (!cachedIpcRenderer) {
+    cachedIpcRenderer = resolveIpcRenderer()
+  }
+
+  if (!cachedIpcRenderer) {
+    throw new Error('ipcRenderer is not available in the current runtime environment')
+  }
+
+  return cachedIpcRenderer
 }
 
+/**
+ * @deprecated This class is deprecated and will be removed in the future.
+ * Due to the new secret system, ipc message transmission should unique Key, and will inject when ui view attached.
+ */
 class TouchChannel implements ITouchClientChannel {
   channelMap: Map<string, Function[]> = new Map();
 
@@ -25,10 +50,12 @@ class TouchChannel implements ITouchClientChannel {
 
   plugin: string;
 
+  private ipcRenderer: IpcRenderer
+
   constructor(pluginName: string) {
     this.plugin = pluginName;
-
-    ipcRenderer.on("@plugin-process-message", this.__handle_main.bind(this));
+    this.ipcRenderer = ensureIpcRenderer()
+    this.ipcRenderer.on("@plugin-process-message", this.__handle_main.bind(this));
   }
 
   __parse_raw_data(e: IpcRendererEvent | undefined, arg: any): RawStandardChannelData | null {
@@ -160,7 +187,7 @@ class TouchChannel implements ITouchClientChannel {
 
     return new Promise((resolve) => {
 
-      ipcRenderer.send("@plugin-process-message", data);
+      this.ipcRenderer.send("@plugin-process-message", data);
 
       this.pendingMap.set(uniqueId, (res: any) => {
         this.pendingMap.delete(uniqueId);
@@ -182,7 +209,7 @@ class TouchChannel implements ITouchClientChannel {
       },
     } as RawStandardChannelData;
 
-    const res = this.__parse_raw_data(void 0, ipcRenderer.sendSync("@plugin-process-message", data))!
+    const res = this.__parse_raw_data(void 0, this.ipcRenderer.sendSync("@plugin-process-message", data))!
 
     if ( res.header.status === 'reply' ) return res.data;
 
@@ -191,12 +218,17 @@ class TouchChannel implements ITouchClientChannel {
   }
 }
 
-let touchChannel: ITouchClientChannel
+let touchChannel: ITouchClientChannel | null = null
 
-export function genChannel() {
+export function genChannel(): ITouchClientChannel {
   if (!touchChannel) {
-    // @ts-ignore
-    touchChannel = window.$channel = new TouchChannel(window.$plugin.name)
+    if (typeof window === 'undefined' || !(window as any)?.$plugin?.name) {
+      throw new Error('TouchChannel cannot be initialized outside plugin renderer context')
+    }
+
+    const pluginName = (window as any).$plugin.name as string
+    touchChannel = new TouchChannel(pluginName)
+    ;(window as any).$channel = touchChannel
   }
 
   return touchChannel

package/plugin/index.ts

@@ -1,5 +1,6 @@
 import { Arch, SupportOS } from './../base/index';
-import { PluginLogger } from './log/logger';
+import type { IPluginLogger } from './log/types';
+import type { PluginInstallRequest, PluginInstallSummary } from './providers';
 
 export enum PluginStatus {
   DISABLED,
@@ -12,11 +13,23 @@ export enum PluginStatus {
 
   LOADING,
   LOADED,
+  LOAD_FAILED,
+}
+
+export interface PluginIssue {
+  type: 'error' | 'warning'
+  message: string
+  source?: string // e.g., 'manifest.json', 'feature:feature-id', 'icon'
+  meta?: any
+  code?: string
+  suggestion?: string
+  timestamp?: number
 }
 
 export interface IPluginIcon {
   type: string | 'remixicon' | 'class'
   value: any
+  _value?: string
 
   init(): Promise<void>
 }
@@ -40,24 +53,21 @@ export interface IPluginBaseInfo {
   desc: string
   icon: IPluginIcon
   platforms: IPlatform
+  _uniqueChannelKey: string
 }
 
 export interface IPluginDev {
   enable: boolean
   address: string
+  source?: string // 修改此处，允许 source 为字符串或 undefined
 }
 
-export interface IPluginWebview {
-}
-
-
-
 export interface ITouchPlugin extends IPluginBaseInfo {
   dev: IPluginDev
-  webViewInit: boolean
-  logger: PluginLogger
-  webview: IPluginWebview
+  pluginPath: string
+  logger: IPluginLogger<any>
   features: IPluginFeature[]
+  issues: PluginIssue[]
 
   addFeature(feature: IPluginFeature): boolean
   delFeature(featureId: string): boolean
@@ -87,6 +97,15 @@ export interface IPluginFeature {
   push: boolean
   platform: IPlatform
   commands: IFeatureCommand[]
+  interaction?: IFeatureInteraction
+}
+
+export type IFeatureInteraction = {
+  type: 'webcontent' | 'widget'
+  /**
+   * The relative path to the html file from the plugin root.
+   */
+  path?: string
 }
 
 /**
@@ -106,8 +125,9 @@ export interface IFeatureLifeCycle {
    * @param id - Feature ID
    * @param data - The triggering payload
    * @param feature - The full feature definition
+   * @param signal - An AbortSignal to cancel the operation
    */
-  onFeatureTriggered(id: string, data: any, feature: IPluginFeature): void
+  onFeatureTriggered(id: string, data: any, feature: IPluginFeature, signal?: AbortSignal): void
 
   /**
    * Called when user input changes within this feature’s input box.
@@ -130,6 +150,14 @@ export interface IFeatureLifeCycle {
    * @param feature - The feature instance being closed
    */
   onClose?(feature: IPluginFeature): void
+
+  /**
+   * Called when an item generated by this feature is executed.
+   * This is used for handling actions on the items themselves,
+   * rather than triggering a new feature.
+   * @param item The TuffItem that was executed.
+   */
+  onItemAction?(item: any): Promise<any>
 }
 
 /**
@@ -172,45 +200,181 @@ export interface ITargetFeatureLifeCycle {
    * @param feature - The feature instance being closed
    */
   onClose?(feature: IPluginFeature): void
+
+  /**
+   * Called when an item generated by this feature is executed.
+   * This is used for handling actions on the items themselves,
+   * rather than triggering a new feature.
+   * @param item The TuffItem that was executed.
+   */
+  onItemAction?(item: any): Promise<any>
+}
+
+/**
+ * Defines the types of plugin sources supported by the system.
+ * This enum allows for clear identification and selection of different plugin resolution and download mechanisms.
+ */
+export enum PluginSourceType {
+  /**
+   * Represents the proprietary TPEX plugin format, typically a compressed package.
+   */
+  TPEX = 'tpex',
+  /**
+   * Represents plugins distributed as standard npm packages.
+   */
+  NPM = 'npm',
+  /**
+   * Represents a local file system plugin source, typically used for development or manual installation.
+   */
+  FILE_SYSTEM = 'file_system',
 }
 
+import type { FSWatcher } from 'chokidar'
+
 export interface IPluginManager {
   plugins: Map<string, ITouchPlugin>
   active: string | null
+  reloadingPlugins: Set<string>
+  enabledPlugins: Set<string>
+  dbUtils: any // Temporarily any, as DbUtils is internal to core-app
+  initialLoadPromises: Promise<boolean>[]
   pluginPath: string
+  watcher: FSWatcher | null
+  devWatcher: any // Temporarily any, as DevPluginWatcher is internal to core-app
 
+  getPluginList(): Array<object>
   setActivePlugin(pluginName: string): boolean
-
+  hasPlugin(name: string): boolean
+  getPluginByName(name: string): ITouchPlugin | undefined
+  reloadPlugin(pluginName: string): Promise<void>
+  persistEnabledPlugins(): Promise<void>
+  listPlugins(): Promise<Array<string>>
   loadPlugin(pluginName: string): Promise<boolean>
   unloadPlugin(pluginName: string): Promise<boolean>
+  installFromSource(request: PluginInstallRequest): Promise<PluginInstallSummary>
 }
 
+/**
+ * Interface representing a unified plugin manifest.
+ * This interface combines fields from the original `IManifest` and `IPluginManifest`
+ * to provide a comprehensive and consistent metadata structure for all plugin types (tpex and npm).
+ */
 export interface IManifest {
-  name: string
-  version: string
-  description: string
+  /**
+   * Unique identifier for the plugin.
+   * This is typically the package name for npm plugins or a unique string for tpex plugins.
+   */
+  id: string;
+  /**
+   * Display name of the plugin.
+   * This is the human-readable name shown to users.
+   */
+  name: string;
+  /**
+   * Version of the plugin, following semantic versioning (e.g., "1.0.0").
+   */
+  version: string;
+  /**
+   * Short description of the plugin's functionality.
+   */
+  description: string;
+  /**
+   * Author of the plugin, typically a name or email.
+   */
+  author: string;
+  /**
+   * Main entry file for the plugin logic, relative to the plugin's root directory.
+   * This file will be loaded when the plugin is activated.
+   */
+  main: string;
+  /**
+   * Optional icon path or definition for the plugin.
+   * This could be a file path to an image or a specific icon class/identifier.
+   */
+  icon?: string;
+  /**
+   * Optional keywords for activating the plugin, e.g., for search or command matching.
+   * These keywords help users discover and launch the plugin.
+   */
+  activationKeywords?: string[];
+  /**
+   * Optional digital signature of the plugin package, used for verification.
+   */
+  _signature?: string;
+  /**
+   * Optional list of files included in the plugin package.
+   * This can be used for integrity checks or resource management.
+   */
+  _files?: string[];
+  /**
+   * Development-specific configuration for the plugin.
+   * This section is used during plugin development and might not be present in production builds.
+   */
   plugin?: {
     dev: {
-      enable: boolean
-      address: string
-    }
-  }
+      /**
+       * Whether development mode is enabled for the plugin.
+       * If true, specific development features or debugging tools might be activated.
+       */
+      enable: boolean;
+      /**
+       * Address for development server or resources.
+       * For example, a local URL where the plugin's frontend assets are served during development.
+       */
+      address: string;
+    };
+  };
+  /**
+   * Build-specific configuration for the plugin.
+   * This section defines how the plugin is built, packaged, and verified.
+   */
   build?: {
-    files: string[]
+    /**
+     * List of files to include in the build.
+     */
+    files: string[];
+    /**
+     * Secret configuration for the build process.
+     */
     secret: {
-      pos: string
-      addon: string[]
-    }
+      pos: string;
+      addon: string[];
+    };
+    /**
+     * Verification settings for the plugin build.
+     * Defines how the authenticity and integrity of the plugin are checked.
+     */
     verify?: {
-      enable: boolean
-      online: 'custom' | 'always' | 'once'
-    }
+      /**
+       * Whether online verification is enabled.
+       */
+      enable: boolean;
+      /**
+       * Online verification strategy.
+       */
+      online: 'custom' | 'always' | 'once';
+    };
+    /**
+     * Version update settings for the plugin.
+     * Defines how the plugin handles updates and downgrades.
+     */
     version?: {
-      update: 'auto' | 'ask' | 'readable'
-      downgrade: boolean
-    }
-  }
+      /**
+       * Update strategy for the plugin:
+       * - 'auto': Automatically updates the plugin.
+       * - 'ask': Prompts the user before updating.
+       * - 'readable': Provides a readable update notification.
+       */
+      update: 'auto' | 'ask' | 'readable';
+      /**
+       * Whether downgrading the plugin version is allowed.
+       */
+      downgrade: boolean;
+    };
+  };
 }
 
-export * from './log/logger'
+export type { LogLevel, LogItem, LogDataType, IPluginLogger } from './log/types'
 export * from './sdk/index'
+export * from './providers'
+export * from './risk'

package/plugin/log/types.ts

@@ -25,3 +25,14 @@ export interface LogItem {
   /** Additional log data (parameters, configs, responses) */
   data: LogDataType[]
 }
+
+/**
+ * Minimal contract for plugin loggers so web 端只依赖接口定义
+ */
+export interface IPluginLogger<TManager = unknown> {
+  info(...args: LogDataType[]): void
+  warn(...args: LogDataType[]): void
+  error(...args: LogDataType[]): void
+  debug(...args: LogDataType[]): void
+  getManager(): TManager
+}

package/plugin/node/index.ts

@@ -0,0 +1,4 @@
+export * from '..'
+export { PluginLogger } from './logger'
+export { PluginLoggerManager } from './logger-manager'
+export type { LogLevel, LogItem, LogDataType, IPluginLogger } from '../log/types'

package/plugin/node/logger-manager.ts

@@ -0,0 +1,113 @@
+import fs from 'fs'
+import path from 'path'
+import { LogItem } from '../log/types'
+import { ITouchPlugin } from '..'
+import { structuredStrictStringify } from '@talex-touch/utils'
+
+/**
+ * PluginLoggerManager is responsible for managing and writing logs for a specific plugin.
+ */
+export class PluginLoggerManager {
+  private readonly pluginInfo: ITouchPlugin
+  private readonly pluginLogDir: string
+  private readonly sessionLogPath: string
+  private readonly pluginInfoPath: string
+  private buffer: LogItem[] = []
+  private flushInterval: NodeJS.Timeout
+  private onLogAppend?: (log: LogItem) => void
+
+  /**
+   * Initializes a new PluginLoggerManager instance.
+   * @param baseDir - Base directory to store logs.
+   * @param pluginInfo - Plugin information for logging context.
+   * @param onLogAppend - Optional callback to be invoked when a log is appended.
+   */
+  constructor(baseDir: string, pluginInfo: ITouchPlugin, onLogAppend?: (log: LogItem) => void) {
+    this.pluginInfo = pluginInfo
+    this.onLogAppend = onLogAppend
+    const timestamp = new Date().toISOString().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.flushInterval = setInterval(() => this.flush(), 5000)
+  }
+
+  /**
+   * Appends a new log item to the buffer.
+   * @param log - The log entry to append.
+   */
+  append(log: LogItem): void {
+    this.buffer.push(log)
+    this.onLogAppend?.(log)
+  }
+
+  /**
+   * Flushes all buffered log items to the current session log file.
+   */
+  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 = []
+  }
+
+  /**
+   * Returns the path to the current session log file.
+   * @returns The path to the session log.
+   */
+  public getSessionLogPath(): string {
+    return this.sessionLogPath
+  }
+
+  /**
+   * Returns the current log buffer.
+   * @returns An array of log items.
+   */
+  public getBuffer(): LogItem[] {
+    return this.buffer
+  }
+
+  /**
+   * Stops the flush interval and ensures remaining logs are written.
+   */
+  destroy(): void {
+    clearInterval(this.flushInterval)
+    this.flush()
+  }
+
+  /**
+   * Creates the touch-plugin.info file with plugin information.
+   */
+  private createPluginInfoFile(): void {
+    const pluginInfo = {
+      name: this.pluginInfo.name,
+      version: this.pluginInfo.version,
+      description: this.pluginInfo.desc,
+      sessionStart: new Date().toISOString(),
+      icon: this.pluginInfo.icon,
+      platforms: this.pluginInfo.platforms,
+      status: this.pluginInfo.status,
+      features: this.pluginInfo.features.map(feature => ({
+        id: feature.id,
+        name: feature.name,
+        desc: feature.desc
+      }))
+    }
+
+    fs.writeFileSync(this.pluginInfoPath, JSON.stringify(pluginInfo, null, 2))
+  }
+
+  /**
+   * Ensures the log directory exists.
+   */
+  private ensureDirectory(): void {
+    if (!fs.existsSync(this.pluginLogDir)) {
+      fs.mkdirSync(this.pluginLogDir, { recursive: true })
+    }
+  }
+}

package/plugin/{log → node}/logger.ts

@@ -1,24 +1,25 @@
-import { LogLevel, LogItem, LogDataType } from './types'
-import { LoggerManager } from './logger-manager'
+import { IPluginLogger, LogLevel, LogItem, LogDataType } from '../log/types'
+import { PluginLoggerManager } from './logger-manager'
+import chalk from 'chalk'
 
 /**
  * PluginLogger provides structured logging capabilities for individual plugins.
  */
-export class PluginLogger {
+export class PluginLogger implements IPluginLogger<PluginLoggerManager> {
   private readonly pluginName: string
-  private readonly manager: LoggerManager
+  private readonly manager: PluginLoggerManager
 
   /**
    * Get logger manager
    */
-  getManager(): LoggerManager { return this.manager }
+  getManager(): PluginLoggerManager { return this.manager }
 
   /**
    * Creates an instance of PluginLogger.
    * @param pluginName - The name of the plugin.
    * @param manager - The logger manager instance controlling log file storage.
    */
-  constructor(pluginName: string, manager: LoggerManager) {
+  constructor(pluginName: string, manager: PluginLoggerManager) {
     this.pluginName = pluginName
     this.manager = manager
   }
@@ -62,14 +63,47 @@ export class PluginLogger {
    */
   private log(level: LogLevel, ...args: LogDataType[]): void {
     const [message, ...data] = args
+
+    const normalizedLevel = (typeof level === 'string' ? level.toUpperCase() : level) as string
+    const allowedLevels: LogLevel[] = ['INFO', 'WARN', 'ERROR', 'DEBUG']
+    const resolvedLevel = (allowedLevels.includes(normalizedLevel as LogLevel)
+      ? (normalizedLevel as LogLevel)
+      : 'INFO')
+    if (resolvedLevel === 'INFO' && normalizedLevel !== 'INFO') {
+      console.warn(
+        `${chalk.bgMagenta('[PluginLog]')} ${chalk.bgYellow('WARN')} ${this.pluginName} - Unknown log level "${String(level)}", fallback to INFO`
+      )
+    }
+
+    const levelColorMap: Record<LogLevel, (input: string) => string> = {
+      INFO: chalk.bgBlue,
+      WARN: chalk.bgYellow,
+      ERROR: chalk.bgRed,
+      DEBUG: chalk.bgGray
+    }
+    const colorize = levelColorMap[resolvedLevel] ?? ((input: string) => input)
+
     const log: LogItem = {
       timestamp: new Date().toISOString(),
-      level,
+      level: resolvedLevel,
       plugin: this.pluginName,
       message: String(message),
       tags: [],
       data,
     }
     this.manager.append(log)
+
+    if (resolvedLevel === 'DEBUG') {
+      console.debug(
+        `${chalk.bgMagenta('[PluginLog]')} ${colorize(resolvedLevel)} ${this.pluginName} - ${message}`,
+        ...data
+      )
+    } else {
+      console.log(
+        `${chalk.bgMagenta('[PluginLog]')} ${colorize(resolvedLevel)} ${this.pluginName} - ${message}`,
+        ...data
+      )
+    }
+
   }
 }