@talex-touch/utils 1.0.40 → 1.0.44

package/plugin/index.ts

@@ -4,7 +4,7 @@ import type { Arch, SupportOS } from './../base/index'
 
 import type { IPluginLogger } from './log/types'
 
-import type { PluginInstallRequest, PluginInstallSummary } from './providers'
+import type { PluginInstallRequest, PluginInstallSummary } from './providers/types'
 
 export enum PluginStatus {
   DISABLED,
@@ -33,6 +33,14 @@ export interface PluginIssue {
   timestamp?: number
 }
 
+export interface PluginMeta {
+  /**
+   * Internal plugins are created in code (no manifest / scanning).
+   * They should be hidden in UI unless developer mode is enabled.
+   */
+  internal?: boolean
+}
+
 export interface DevServerHealthCheckResult {
   healthy: boolean
   version?: string
@@ -68,13 +76,44 @@ export interface IPluginDev {
   source?: boolean
 }
 
+/**
+ * SDK API version for plugin compatibility checking.
+ * Format: YYMMDD (e.g., 251212 = 2025-12-12)
+ *
+ * Rules:
+ * - Not declared or < PERMISSION_ENFORCEMENT_MIN_VERSION: legacy mode (permissions bypassed)
+ * - >= PERMISSION_ENFORCEMENT_MIN_VERSION: permissions enforced
+ */
+export type SdkApiVersion = number
+
 export interface ITouchPlugin extends IPluginBaseInfo {
   dev: IPluginDev
   pluginPath: string
   logger: IPluginLogger<any>
+  /**
+   * Category id synced with Nexus (e.g., 'utilities', 'productivity').
+   * Used for UI grouping and marketplace filtering.
+   */
+  category?: string
+  meta?: PluginMeta
   features: IPluginFeature[]
   issues: PluginIssue[]
   divisionBoxConfig?: import('../types/division-box').ManifestDivisionBoxConfig
+  /**
+   * SDK API version declared by the plugin.
+   * Used for compatibility checking and permission enforcement.
+   * Format: YYMMDD (e.g., 251212)
+   */
+  sdkapi?: SdkApiVersion
+  /**
+   * Declared permissions from manifest.
+   * Used for permission checking and UI display.
+   */
+  declaredPermissions?: {
+    required: string[]
+    optional: string[]
+    reasons: Record<string, string>
+  }
 
   addFeature: (feature: IPluginFeature) => boolean
   delFeature: (featureId: string) => boolean
@@ -102,14 +141,21 @@ export interface ITouchPlugin extends IPluginBaseInfo {
    * @param content The content of the file.
    * @returns The result of the save operation.
    */
-  savePluginFile: (fileName: string, content: object) => { success: boolean, error?: string }
+  savePluginFile: (
+    fileName: string,
+    content: object,
+    options?: { broadcast?: boolean }
+  ) => { success: boolean, error?: string }
 
   /**
    * Delete the plugin file.
    * @param fileName The name of the file.
    * @returns The result of the delete operation.
    */
-  deletePluginFile: (fileName: string) => { success: boolean, error?: string }
+  deletePluginFile: (
+    fileName: string,
+    options?: { broadcast?: boolean }
+  ) => { success: boolean, error?: string }
 
   /**
    * List all files in the plugin.
@@ -133,10 +179,13 @@ export interface ITouchPlugin extends IPluginBaseInfo {
 
 export interface IFeatureCommand {
   type: 'match' | 'contain' | 'regex' | 'function' | 'over' | 'image' | 'files' | 'directory' | 'window'
-  value: string | string[] | RegExp | Function
-  onTrigger: () => void
+  value: string | string[] | RegExp | FeatureCommandMatcher
+  /** Optional trigger callback - not serialized over IPC */
+  onTrigger?: () => void
 }
 
+export type FeatureCommandMatcher = (queryText: string) => boolean
+
 export interface IPluginFeature {
   id: string
   name: string
@@ -147,6 +196,10 @@ export interface IPluginFeature {
   platform: IPlatform
   commands: IFeatureCommand[]
   interaction?: IFeatureInteraction
+  /**
+   * Experimental features are hidden unless the plugin runs in dev mode.
+   */
+  experimental?: boolean
   /**
    * Internal search tokens generated at runtime for better matching
    */
@@ -174,6 +227,17 @@ export interface IFeatureInteraction {
    * The relative path to the html file from the plugin root.
    */
   path?: string
+  /**
+   * Whether to show the input field in CoreBox when this feature is active.
+   * Defaults to true for webcontent type.
+   */
+  showInput?: boolean
+  /**
+   * Whether to automatically enable input monitoring for this feature.
+   * If true, plugin will receive input change events without calling allowInput().
+   * Defaults to true for webcontent features.
+   */
+  allowInput?: boolean
 }
 
 /**
@@ -390,6 +454,16 @@ export interface IManifest {
    * Version of the plugin, following semantic versioning (e.g., "1.0.0").
    */
   version: string
+  /**
+   * SDK API version for compatibility checking.
+   * Format: YYMMDD (e.g., 251212 = 2025-12-12)
+   * Plugins without this field or with version < 251212 will bypass permission enforcement.
+   */
+  sdkapi?: SdkApiVersion
+  /**
+   * Category id synced with Nexus (e.g., 'utilities', 'productivity').
+   */
+  category?: string
   /**
    * Short description of the plugin's functionality.
    */
@@ -499,8 +573,8 @@ export interface IManifest {
 }
 
 export * from './install'
-export type { IPluginLogger, LogDataType, LogItem, LogLevel } from './log/types'
-export * from './providers'
+export type { IPluginLogger, LogDataType, LogItem } from './log/types'
 export * from './risk'
-export * from './sdk/index'
+export * from './sdk-version'
+// Plugin runtime SDK should be imported from `@talex-touch/utils/plugin/sdk` to avoid root export collisions.
 export * from './widget'

package/plugin/install.ts

@@ -1,6 +1,7 @@
 export type PluginInstallTaskStage
   = | 'queued'
     | 'downloading'
+    | 'verifying'
     | 'awaiting-confirmation'
     | 'installing'
     | 'completed'
@@ -20,6 +21,8 @@ export interface PluginInstallProgressEvent {
   /** 插件唯一标识或名称（由客户端提供）。 */
   pluginId?: string
   pluginName?: string
+  /** 来源提供者 ID，用于区分不同市场源的同名插件。 */
+  providerId?: string
   /** 队列中的剩余任务数量（包含当前任务）。 */
   remaining?: number
   /** 当前任务在队列中的位置（0 表示正在处理）。 */

package/plugin/log/types.ts

@@ -1,7 +1,24 @@
+import type { LogLevelString as BaseLogLevelString } from '../../base/log-level'
 /**
- * Defines supported logging levels.
+ * Re-export unified LogLevel from base
  */
-export type LogLevel = 'INFO' | 'WARN' | 'ERROR' | 'DEBUG'
+import {
+  LogLevel as BaseLogLevel,
+
+  logLevelToString as baseLogLevelToString,
+  stringToLogLevel as baseStringToLogLevel,
+} from '../../base/log-level'
+
+export const LogLevel = BaseLogLevel
+export type LogLevelString = BaseLogLevelString
+export const logLevelToString = baseLogLevelToString
+export const stringToLogLevel = baseStringToLogLevel
+
+/**
+ * Legacy string-based log level type (for backward compatibility)
+ * @deprecated Use LogLevel enum instead
+ */
+export type LogLevelLegacy = 'INFO' | 'WARN' | 'ERROR' | 'DEBUG'
 
 /**
  * Supported data types for logging arguments.
@@ -14,8 +31,8 @@ export type LogDataType = string | number | boolean | object
 export interface LogItem {
   /** ISO timestamp when the log was created */
   timestamp: string
-  /** Logging severity level */
-  level: LogLevel
+  /** Logging severity level (uppercase string for storage compatibility) */
+  level: LogLevelString
   /** Plugin name */
   plugin: string
   /** Main log message */
@@ -27,7 +44,7 @@ export interface LogItem {
 }
 
 /**
- * Minimal contract for plugin loggers so web 端只依赖接口定义
+ * Minimal contract for plugin loggers
  */
 export interface IPluginLogger<TManager = unknown> {
   info: (...args: LogDataType[]) => void

package/plugin/node/logger-manager.ts

@@ -3,6 +3,7 @@ import type { LogItem } from '../log/types'
 import fs from 'node:fs'
 import path from 'node:path'
 import { structuredStrictStringify } from '@talex-touch/utils'
+import { PollingService } from '../../common/utils/polling'
 
 /**
  * PluginLoggerManager is responsible for managing and writing logs for a specific plugin.
@@ -14,7 +15,8 @@ export class PluginLoggerManager {
   private readonly pluginInfoPath: string
   private readonly sessionStart: string
   private buffer: LogItem[] = []
-  private flushInterval: NodeJS.Timeout
+  private readonly pollingService = PollingService.getInstance()
+  private readonly flushTaskId: string
   private onLogAppend?: (log: LogItem) => void
 
   /**
@@ -33,9 +35,15 @@ export class PluginLoggerManager {
     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.flushTaskId = `plugin-logger.flush.${pluginInfo.name}.${Date.now()}`
 
     this.ensureLogEnvironment(true)
-    this.flushInterval = setInterval(() => this.flush(), 5000)
+    this.pollingService.register(
+      this.flushTaskId,
+      () => this.flush(),
+      { interval: 5, unit: 'seconds' },
+    )
+    this.pollingService.start()
   }
 
   /**
@@ -89,7 +97,7 @@ export class PluginLoggerManager {
    * Stops the flush interval and ensures remaining logs are written.
    */
   destroy(): void {
-    clearInterval(this.flushInterval)
+    this.pollingService.unregister(this.flushTaskId)
     this.flush()
   }
 

package/plugin/node/logger.ts

@@ -1,7 +1,18 @@
-import type { IPluginLogger, LogDataType, LogItem, LogLevel } from '../log/types'
+import type { IPluginLogger, LogDataType, LogItem, LogLevelString } from '../log/types'
 import type { PluginLoggerManager } from './logger-manager'
+import process from 'node:process'
+import { inspect } from 'node:util'
 import chalk from 'chalk'
 
+const pluginLogStdout =
+  process.env.TALEX_PLUGIN_LOG_STDOUT === '1' || process.env.TALEX_PLUGIN_LOG_STDOUT === 'true'
+const defaultStdoutLevels = new Set<LogLevelString>(['WARN', 'ERROR'])
+
+function shouldWriteToStdout(level: LogLevelString): boolean {
+  if (pluginLogStdout) return true
+  return defaultStdoutLevels.has(level)
+}
+
 /**
  * PluginLogger provides structured logging capabilities for individual plugins.
  */
@@ -61,13 +72,13 @@ export class PluginLogger implements IPluginLogger<PluginLoggerManager> {
    * @param level - The severity level of the log.
    * @param args - The log message and optional data payload.
    */
-  private log(level: LogLevel, ...args: LogDataType[]): void {
+  private log(level: LogLevelString, ...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)
+    const allowedLevels: LogLevelString[] = ['INFO', 'WARN', 'ERROR', 'DEBUG']
+    const resolvedLevel = (allowedLevels.includes(normalizedLevel as LogLevelString)
+      ? (normalizedLevel as LogLevelString)
       : 'INFO')
     if (resolvedLevel === 'INFO' && normalizedLevel !== 'INFO') {
       console.warn(
@@ -75,11 +86,12 @@ export class PluginLogger implements IPluginLogger<PluginLoggerManager> {
       )
     }
 
-    const levelColorMap: Record<LogLevel, (input: string) => string> = {
+    const levelColorMap: Record<LogLevelString, (input: string) => string> = {
       INFO: chalk.bgBlue,
       WARN: chalk.bgYellow,
       ERROR: chalk.bgRed,
       DEBUG: chalk.bgGray,
+      NONE: chalk.bgBlack,
     }
     const colorize = levelColorMap[resolvedLevel] ?? ((input: string) => input)
 
@@ -93,17 +105,12 @@ export class PluginLogger implements IPluginLogger<PluginLoggerManager> {
     }
     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,
-      )
+    if (shouldWriteToStdout(resolvedLevel)) {
+      const baseMessage = `${chalk.bgMagenta('[PluginLog]')} ${colorize(resolvedLevel)} ${this.pluginName} - ${message}`
+      const extra = data.length
+        ? ` ${data.map(item => (typeof item === 'string' ? item : inspect(item))).join(' ')}`
+        : ''
+      process.stdout.write(`${baseMessage}${extra}\n`)
     }
   }
 }

package/plugin/preload.ts

@@ -1,5 +1,9 @@
 import type { ITouchClientChannel } from '../channel'
+import type { ITuffTransport } from '../transport'
 import type { ITouchSDK } from './sdk/index'
+import { getLogger } from '../common/logger'
+import { createPluginTuffTransport } from '../transport'
+import { defineRawEvent } from '../transport/event/builder'
 // Import SDK for side effects (initializes hooks)
 import './sdk/index'
 
@@ -9,8 +13,11 @@ declare global {
     $plugin: {
       name: string
       path: object
+      version?: string
+      sdkapi?: number
     }
     $channel: ITouchClientChannel
+    $transport?: ITuffTransport
     $crash: (message: string, extraData: any) => void
     $config: {
       themeStyle: any
@@ -19,14 +26,30 @@ declare global {
   }
 }
 
+const preloadLog = getLogger('plugin-preload')
+const crashEvent = defineRawEvent<Record<string, string | number | boolean | undefined>, void>('crash')
+
 export function initTuff(window: Window) {
   const plugin = window.$plugin
   if (!plugin)
     throw new Error('Plugin has a fatal error! Please check your plugin!')
 
+  if (!window.$transport && window.$channel) {
+    window.$transport = createPluginTuffTransport(window.$channel)
+  }
+  if (window.$transport) {
+    window.addEventListener?.('beforeunload', () => {
+      window.$transport?.destroy()
+    }, { once: true })
+  }
+
   window.$crash = function (message, extraData) {
-    window.$channel.send('crash', { message, ...extraData })
+    if (window.$transport) {
+      void window.$transport.send(crashEvent, { message, ...extraData })
+      return
+    }
+    window.$channel?.send?.('crash', { message, ...extraData })
   }
 
-  console.log(`%c[Plugin] ${plugin.name} loaded`, 'color: #42b983')
+  preloadLog.info(`[Plugin] ${plugin.name} loaded`)
 }

package/plugin/providers/index.ts

@@ -1,2 +1,6 @@
+export * from './market-client'
+export * from './npm-provider'
 export * from './registry'
+export * from './tpex-provider'
+export * from './tpex-types'
 export * from './types'

package/plugin/providers/market-client.ts

@@ -0,0 +1,218 @@
+import type { NpmPackageInfo } from './npm-provider'
+import type { TpexPluginInfo } from './tpex-provider'
+import { NpmProvider } from './npm-provider'
+import { TpexProvider } from './tpex-provider'
+import { PluginProviderType } from './types'
+
+export type PluginSourceType = 'tpex' | 'npm' | 'all'
+
+export interface MarketPluginInfo {
+  id: string
+  name: string
+  slug: string
+  version: string
+  description: string
+  author: string
+  icon?: string
+  source: PluginSourceType
+  isOfficial: boolean
+  downloads?: number
+  category?: string
+  keywords?: string[]
+  homepage?: string
+  packageUrl?: string
+  raw: TpexPluginInfo | NpmPackageInfo
+}
+
+export interface MarketSearchOptions {
+  keyword?: string
+  source?: PluginSourceType
+  category?: string
+  limit?: number
+  offset?: number
+}
+
+export interface MarketSearchResult {
+  plugins: MarketPluginInfo[]
+  total: number
+  sources: {
+    tpex: number
+    npm: number
+  }
+}
+
+function normalizeTpexPlugin(plugin: TpexPluginInfo): MarketPluginInfo {
+  return {
+    id: plugin.id,
+    name: plugin.name,
+    slug: plugin.slug,
+    version: plugin.latestVersion?.version ?? '0.0.0',
+    description: plugin.summary,
+    author: plugin.author?.name ?? 'Unknown',
+    icon: plugin.iconUrl ?? undefined,
+    source: 'tpex',
+    isOfficial: plugin.isOfficial,
+    downloads: plugin.installs,
+    category: plugin.category,
+    homepage: plugin.homepage ?? undefined,
+    packageUrl: plugin.latestVersion?.packageUrl,
+    raw: plugin,
+  }
+}
+
+function normalizeNpmPlugin(pkg: NpmPackageInfo): MarketPluginInfo {
+  const authorName = typeof pkg.author === 'string'
+    ? pkg.author
+    : pkg.author?.name ?? 'Unknown'
+
+  return {
+    id: pkg.name,
+    name: pkg.name.replace(/^tuff-plugin-/, '').replace(/^@tuff\//, ''),
+    slug: pkg.name,
+    version: pkg.version,
+    description: pkg.description ?? '',
+    author: authorName,
+    icon: pkg.tuff?.icon,
+    source: 'npm',
+    isOfficial: pkg.name.startsWith('@tuff/'),
+    keywords: pkg.keywords,
+    packageUrl: pkg.dist.tarball,
+    raw: pkg,
+  }
+}
+
+/**
+ * Unified plugin market client supporting multiple sources
+ */
+export class PluginMarketClient {
+  private tpexProvider: TpexProvider
+  private npmProvider: NpmProvider
+
+  constructor(options?: {
+    tpexApiBase?: string
+    npmRegistry?: string
+  }) {
+    this.tpexProvider = new TpexProvider(options?.tpexApiBase)
+    this.npmProvider = new NpmProvider(options?.npmRegistry)
+  }
+
+  /**
+   * Search plugins from all sources
+   */
+  async search(options: MarketSearchOptions = {}): Promise<MarketSearchResult> {
+    const { keyword, source = 'all', limit = 50, offset = 0 } = options
+    const results: MarketPluginInfo[] = []
+    let tpexCount = 0
+    let npmCount = 0
+
+    if (source === 'all' || source === 'tpex') {
+      try {
+        const tpexPlugins = keyword
+          ? await this.tpexProvider.searchPlugins(keyword)
+          : await this.tpexProvider.listPlugins()
+
+        const normalized = tpexPlugins.map(normalizeTpexPlugin)
+        results.push(...normalized)
+        tpexCount = normalized.length
+      }
+      catch (error) {
+        console.warn('[MarketClient] TPEX search failed:', error)
+      }
+    }
+
+    if (source === 'all' || source === 'npm') {
+      try {
+        const npmPlugins = await this.npmProvider.searchPlugins(keyword)
+        const normalized = npmPlugins.map(normalizeNpmPlugin)
+        results.push(...normalized)
+        npmCount = normalized.length
+      }
+      catch (error) {
+        console.warn('[MarketClient] NPM search failed:', error)
+      }
+    }
+
+    const sorted = results.sort((a, b) => {
+      if (a.isOfficial !== b.isOfficial)
+        return a.isOfficial ? -1 : 1
+      return (b.downloads ?? 0) - (a.downloads ?? 0)
+    })
+
+    const paginated = sorted.slice(offset, offset + limit)
+
+    return {
+      plugins: paginated,
+      total: results.length,
+      sources: {
+        tpex: tpexCount,
+        npm: npmCount,
+      },
+    }
+  }
+
+  /**
+   * Get plugin details by identifier
+   */
+  async getPlugin(identifier: string, source?: PluginSourceType): Promise<MarketPluginInfo | null> {
+    if (source === 'tpex' || (!source && !identifier.includes('/'))) {
+      try {
+        const plugin = await this.tpexProvider.getPlugin(identifier)
+        if (plugin)
+          return normalizeTpexPlugin(plugin)
+      }
+      catch {
+        // Fall through to npm
+      }
+    }
+
+    if (source === 'npm' || !source) {
+      try {
+        const pkg = await this.npmProvider.getPackageInfo(identifier)
+        if (pkg)
+          return normalizeNpmPlugin(pkg)
+      }
+      catch {
+        // Not found
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Get install source string for a plugin
+   */
+  getInstallSource(plugin: MarketPluginInfo): string {
+    if (plugin.source === 'tpex') {
+      return `tpex:${plugin.slug}`
+    }
+    return `npm:${plugin.id}`
+  }
+
+  /**
+   * Get provider type for a plugin
+   */
+  getProviderType(plugin: MarketPluginInfo): PluginProviderType {
+    return plugin.source === 'tpex'
+      ? PluginProviderType.TPEX
+      : PluginProviderType.NPM
+  }
+
+  /**
+   * List all plugins from official source (TPEX)
+   */
+  async listOfficialPlugins(): Promise<MarketPluginInfo[]> {
+    const plugins = await this.tpexProvider.listPlugins()
+    return plugins.map(normalizeTpexPlugin)
+  }
+
+  /**
+   * List all plugins from npm
+   */
+  async listNpmPlugins(): Promise<MarketPluginInfo[]> {
+    const plugins = await this.npmProvider.listPlugins()
+    return plugins.map(normalizeNpmPlugin)
+  }
+}
+
+export const defaultMarketClient = new PluginMarketClient()