@talex-touch/utils 1.0.14 → 1.0.15

package/plugin/index.ts

@@ -1,121 +1,216 @@
-import { Arch, SupportOS } from './../base/index';
-export enum PluginStatus {
-  DISABLED,
-  DISABLING,
-
-  CRASHED,
-
-  ENABLED,
-  ACTIVE,
-
-  LOADING,
-  LOADED,
-}
-
-export interface IPluginIcon {
-  type: string | 'remixicon' | 'class'
-  value: any
-
-  init(): Promise<void>
-}
-
-export interface IPlatformInfo {
-  enable: boolean
-  arch: Arch[]
-  os: SupportOS[]
-}
-
-export type PlatformKey = 'win' | 'darwin' | 'linux'
-
-export type IPlatform = {
-  [key in PlatformKey]?: IPlatformInfo
-}
-
-export interface IPluginBaseInfo {
-  name: string
-  readme: string
-  version: string
-  desc: string
-  icon: IPluginIcon
-  platforms: IPlatform
-}
-
-export interface IPluginDev {
-  enable: boolean
-  address: string
-}
-
-export interface IPluginWebview {
-}
-
-export interface ITouchPlugin extends IPluginBaseInfo {
-  dev: IPluginDev
-  webViewInit: boolean
-  webview: IPluginWebview
-  features: IPluginFeature[]
-
-  addFeature(feature: IPluginFeature): boolean
-  delFeature(featureId: string): boolean
-  getFeature(featureId: string): IPluginFeature | null
-  getFeatures(): IPluginFeature[]
-
-  get status(): PluginStatus
-  set status(v: PluginStatus)
-
-  enable(): Promise<boolean>
-  disable(): Promise<boolean>
-}
-
-export interface IFeatureCommand {
-  type: "match" | "contain" | "regex" | "function" | "over" | "image" | "files" | "directory" | "window"
-  value: string | string[] | RegExp | Function
-  onTrigger(): void
-}
-
-export interface IPluginFeature {
-  id: string
-  name: string
-  desc: string
-  icon: IPluginIcon
-  push: boolean
-  platform: IPlatform
-  commands: IFeatureCommand[]
-}
-
-export interface IPluginManager {
-  plugins: Map<string, ITouchPlugin>
-  active: string | null
-  pluginPath: string
-
-  setActivePlugin(pluginName: string): boolean
-
-  loadPlugin(pluginName: string): Promise<boolean>
-  unloadPlugin(pluginName: string): Promise<boolean>
-}
-
-export interface IManifest {
-  name: string
-  version: string
-  description: string
-  plugin?: {
-    dev: {
-      enable: boolean
-      address: string
-    }
-  }
-  build?: {
-    files: string[]
-    secret: {
-      pos: string
-      addon: string[]
-    }
-    verify?: {
-      enable: boolean
-      online: 'custom' | 'always' | 'once'
-    }
-    version?: {
-      update: 'auto' | 'ask' | 'readable'
-      downgrade: boolean
-    }
-  }
-}
+import { Arch, SupportOS } from './../base/index';
+import { PluginLogger } from './log/logger';
+
+export enum PluginStatus {
+  DISABLED,
+  DISABLING,
+
+  CRASHED,
+
+  ENABLED,
+  ACTIVE,
+
+  LOADING,
+  LOADED,
+}
+
+export interface IPluginIcon {
+  type: string | 'remixicon' | 'class'
+  value: any
+
+  init(): Promise<void>
+}
+
+export interface IPlatformInfo {
+  enable: boolean
+  arch: Arch[]
+  os: SupportOS[]
+}
+
+export type PlatformKey = 'win' | 'darwin' | 'linux'
+
+export type IPlatform = {
+  [key in PlatformKey]?: IPlatformInfo
+}
+
+export interface IPluginBaseInfo {
+  name: string
+  readme: string
+  version: string
+  desc: string
+  icon: IPluginIcon
+  platforms: IPlatform
+}
+
+export interface IPluginDev {
+  enable: boolean
+  address: string
+}
+
+export interface IPluginWebview {
+}
+
+
+
+export interface ITouchPlugin extends IPluginBaseInfo {
+  dev: IPluginDev
+  webViewInit: boolean
+  logger: PluginLogger
+  webview: IPluginWebview
+  features: IPluginFeature[]
+
+  addFeature(feature: IPluginFeature): boolean
+  delFeature(featureId: string): boolean
+  getFeature(featureId: string): IPluginFeature | null
+  getFeatures(): IPluginFeature[]
+  triggerFeature(feature: IPluginFeature, query: any): void
+  triggerInputChanged(feature: IPluginFeature, query: any): void
+
+  get status(): PluginStatus
+  set status(v: PluginStatus)
+
+  enable(): Promise<boolean>
+  disable(): Promise<boolean>
+}
+
+export interface IFeatureCommand {
+  type: "match" | "contain" | "regex" | "function" | "over" | "image" | "files" | "directory" | "window"
+  value: string | string[] | RegExp | Function
+  onTrigger(): void
+}
+
+export interface IPluginFeature {
+  id: string
+  name: string
+  desc: string
+  icon: IPluginIcon
+  push: boolean
+  platform: IPlatform
+  commands: IFeatureCommand[]
+}
+
+/**
+ * Lifecycle hooks for a feature's behavior within the launcher environment.
+ * These hooks are triggered based on real user interaction and system events.
+ */
+export interface IFeatureLifeCycle {
+  /**
+   * Called when a feature is actively launched from the launcher.
+   * Can be used to prepare data or UI specific to this session.
+   * @param feature - The feature instance being launched
+   */
+  onLaunch?(feature: IPluginFeature): void
+
+  /**
+   * Called when a feature is triggered via a matching command.
+   * @param id - Feature ID
+   * @param data - The triggering payload
+   * @param feature - The full feature definition
+   */
+  onFeatureTriggered(id: string, data: any, feature: IPluginFeature): void
+
+  /**
+   * Called when user input changes within this feature’s input box.
+   * For example, search text or commands typed.
+   * @param input - The new input value
+   */
+  onInputChanged?(input: string): void
+
+  /**
+   * Called when a user selects or clicks an actionable item inside the feature.
+   * For example, selecting a suggestion or executing an option.
+   * @param actionId - A string identifier for the clicked action
+   * @param data - Optional payload associated with that action
+   */
+  onActionClick?(actionId: string, data?: any): void
+
+  /**
+   * Called when the feature is manually closed by the user or by the system.
+   * Useful for cleanup or state saving.
+   * @param feature - The feature instance being closed
+   */
+  onClose?(feature: IPluginFeature): void
+}
+
+/**
+ * Lifecycle hooks for the feature's behavior within the launcher environment.
+ * These hooks are triggered based on real user interaction and system events.
+ */
+export interface ITargetFeatureLifeCycle {
+  /**
+   * Called when the feature is actively launched from the launcher.
+   * Can be used to prepare data or UI specific to this session.
+   * @param feature - The feature instance being launched
+   */
+  onLaunch?(feature: IPluginFeature): void
+
+  /**
+   * Called when the feature is triggered via a matching command.
+   * @param data - The triggering payload
+   * @param feature - The full feature definition
+   */
+  onFeatureTriggered(data: any, feature: IPluginFeature): void
+
+  /**
+   * Called when user input changes within this feature’s input box.
+   * For example, search text or commands typed.
+   * @param input - The new input value
+   */
+  onInputChanged?(input: string): void
+
+  /**
+   * Called when a user selects or clicks an actionable item inside the feature.
+   * For example, selecting a suggestion or executing an option.
+   * @param actionId - A string identifier for the clicked action
+   * @param data - Optional payload associated with that action
+   */
+  onActionClick?(actionId: string, data?: any): void
+
+  /**
+   * Called when the feature is manually closed by the user or by the system.
+   * Useful for cleanup or state saving.
+   * @param feature - The feature instance being closed
+   */
+  onClose?(feature: IPluginFeature): void
+}
+
+export interface IPluginManager {
+  plugins: Map<string, ITouchPlugin>
+  active: string | null
+  pluginPath: string
+
+  setActivePlugin(pluginName: string): boolean
+
+  loadPlugin(pluginName: string): Promise<boolean>
+  unloadPlugin(pluginName: string): Promise<boolean>
+}
+
+export interface IManifest {
+  name: string
+  version: string
+  description: string
+  plugin?: {
+    dev: {
+      enable: boolean
+      address: string
+    }
+  }
+  build?: {
+    files: string[]
+    secret: {
+      pos: string
+      addon: string[]
+    }
+    verify?: {
+      enable: boolean
+      online: 'custom' | 'always' | 'once'
+    }
+    version?: {
+      update: 'auto' | 'ask' | 'readable'
+      downgrade: boolean
+    }
+  }
+}
+
+export * from './log/logger'
+export * from './sdk/index'

package/plugin/log/logger-manager.ts

@@ -0,0 +1,60 @@
+import fs from 'fs'
+import path from 'path'
+import { LogItem } from './types'
+
+/**
+ * LoggerManager is responsible for managing and writing logs for all plugins.
+ */
+export class LoggerManager {
+  private readonly logDir: string
+  private readonly sessionLogPath: string
+  private buffer: LogItem[] = []
+  private flushInterval: NodeJS.Timeout
+
+  /**
+   * Initializes a new LoggerManager instance.
+   * @param baseDir - Base directory to store logs.
+   */
+  constructor(baseDir: string) {
+    this.logDir = path.resolve(baseDir, 'logs')
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+    this.sessionLogPath = path.resolve(this.logDir, `${timestamp}.log`)
+    this.ensureDirectory()
+    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)
+  }
+
+  /**
+   * 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) => JSON.stringify(item)).join('\n') + '\n'
+    fs.appendFileSync(this.sessionLogPath, lines)
+    this.buffer = []
+  }
+
+  /**
+   * Stops the flush interval and ensures remaining logs are written.
+   */
+  destroy(): void {
+    clearInterval(this.flushInterval)
+    this.flush()
+  }
+
+  /**
+   * Ensures the log directory exists.
+   */
+  private ensureDirectory(): void {
+    if (!fs.existsSync(this.logDir)) {
+      fs.mkdirSync(this.logDir, { recursive: true })
+    }
+  }
+}

package/plugin/log/logger.ts

@@ -0,0 +1,75 @@
+import { LogLevel, LogItem, LogDataType } from './types'
+import { LoggerManager } from './logger-manager'
+
+/**
+ * PluginLogger provides structured logging capabilities for individual plugins.
+ */
+export class PluginLogger {
+  private readonly pluginName: string
+  private readonly manager: LoggerManager
+
+  /**
+   * Get logger manager
+   */
+  getManager(): LoggerManager { 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) {
+    this.pluginName = pluginName
+    this.manager = manager
+  }
+
+  /**
+   * Logs an info-level message.
+   * @param args - The log message and optional data payload.
+   */
+  info(...args: LogDataType[]): void {
+    this.log('INFO', ...args)
+  }
+
+  /**
+   * Logs a warning-level message.
+   * @param args - The log message and optional data payload.
+   */
+  warn(...args: LogDataType[]): void {
+    this.log('WARN', ...args)
+  }
+
+  /**
+   * Logs an error-level message.
+   * @param args - The log message and optional data payload.
+   */
+  error(...args: LogDataType[]): void {
+    this.log('ERROR', ...args)
+  }
+
+  /**
+   * Logs a debug-level message.
+   * @param args - The log message and optional data payload.
+   */
+  debug(...args: LogDataType[]): void {
+    this.log('DEBUG', ...args)
+  }
+
+  /**
+   * Constructs a log entry and forwards it to the manager.
+   * @param level - The severity level of the log.
+   * @param args - The log message and optional data payload.
+   */
+  private log(level: LogLevel, ...args: LogDataType[]): void {
+    const [message, ...data] = args
+    const log: LogItem = {
+      timestamp: new Date().toISOString(),
+      level,
+      plugin: this.pluginName,
+      message: String(message),
+      tags: [],
+      data,
+    }
+    this.manager.append(log)
+  }
+}

package/plugin/log/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Defines supported logging levels.
+ */
+export type LogLevel = 'INFO' | 'WARN' | 'ERROR' | 'DEBUG'
+
+/**
+ * Supported data types for logging arguments.
+ */
+export type LogDataType = string | number | boolean | object
+
+/**
+ * Represents a single log entry for a plugin.
+ */
+export interface LogItem {
+  /** ISO timestamp when the log was created */
+  timestamp: string
+  /** Logging severity level */
+  level: LogLevel
+  /** Plugin name */
+  plugin: string
+  /** Main log message */
+  message: string
+  /** Optional log tags for filtering and UI grouping */
+  tags: string[]
+  /** Additional log data (parameters, configs, responses) */
+  data: LogDataType[]
+}

package/plugin/preload.ts

@@ -1,39 +1,39 @@
-import { genChannel } from './channel'
-import './sdk/index'
-
-// window type
-declare global {
-  export interface Window {
-    $plugin: {
-      name: string
-      path: Object
-    }
-    $send: (type: string, data: any) => void
-    $sendSync: (type: string, data: any) => Promise<any>
-    $regChannel: (type: string, callback: Function) => void
-    $crash: (message: string, extraData: any) => void
-    $config: {
-      themeStyle: any
-    }
-  }
-}
-
-export function init(window: Window) {
-  const plugin = window.$plugin
-  if (!plugin)
-    throw new Error('Plugin has a fatal error! Please check your plugin!')
-
-  window.$crash = function (message, extraData) {
-    window.$send('crash', { message, ...extraData })
-  }
-
-  initBridge(window)
-}
-
-export function initBridge(window: Window) {
-  const touchChannel = genChannel()
-
-  window.$send = touchChannel.send.bind(touchChannel)
-  window.$sendSync = touchChannel.sendSync.bind(touchChannel)
-  window.$regChannel = touchChannel.regChannel.bind(touchChannel)
-}
+import { genChannel } from './channel'
+import './sdk/index'
+
+// window type
+declare global {
+  export interface Window {
+    $plugin: {
+      name: string
+      path: Object
+    }
+    $send: (type: string, data: any) => void
+    $sendSync: (type: string, data: any) => Promise<any>
+    $regChannel: (type: string, callback: Function) => void
+    $crash: (message: string, extraData: any) => void
+    $config: {
+      themeStyle: any
+    }
+  }
+}
+
+export function init(window: Window) {
+  const plugin = window.$plugin
+  if (!plugin)
+    throw new Error('Plugin has a fatal error! Please check your plugin!')
+
+  window.$crash = function (message, extraData) {
+    window.$send('crash', { message, ...extraData })
+  }
+
+  initBridge(window)
+}
+
+export function initBridge(window: Window) {
+  const touchChannel = genChannel()
+
+  window.$send = touchChannel.send.bind(touchChannel)
+  window.$sendSync = touchChannel.sendSync.bind(touchChannel)
+  window.$regChannel = touchChannel.regChannel.bind(touchChannel)
+}

package/plugin/sdk/common.ts

@@ -1,28 +1,28 @@
-import { genChannel } from '../channel';
-import { IPluginFeature } from '../index'
-
-export function regShortcut(key: string, func: Function) {
-    const channel = genChannel()
-
-    const res = channel.sendSync('shortcon:reg', { key })
-    if ( res instanceof String ) throw new Error(String(res))
-    if ( res === false ) return false;
-
-    channel.regChannel('shortcon:trigger', ({ data }) => key === data.key && func())
-
-    return true;
-}
-
-export function regFeature(feature: IPluginFeature): boolean {
-  const channel = genChannel()
-
-  return channel.sendSync('feature:reg', { feature })
-}
-
-export function unRegFeature(id: string): boolean {
-  const channel = genChannel()
-
-  return channel.sendSync('feature:unreg', { feature: id })
-}
-
+import { genChannel } from '../channel';
+import { IPluginFeature } from '../index'
+
+export function regShortcut(key: string, func: Function) {
+    const channel = genChannel()
+
+    const res = channel.sendSync('shortcon:reg', { key })
+    if ( res instanceof String ) throw new Error(String(res))
+    if ( res === false ) return false;
+
+    channel.regChannel('shortcon:trigger', ({ data }) => key === data.key && func())
+
+    return true;
+}
+
+export function regFeature(feature: IPluginFeature): boolean {
+  const channel = genChannel()
+
+  return channel.sendSync('feature:reg', { feature })
+}
+
+export function unRegFeature(id: string): boolean {
+  const channel = genChannel()
+
+  return channel.sendSync('feature:unreg', { feature: id })
+}
+
 export * from './window';