@talex-touch/utils 1.0.42 → 1.0.45

package/common/utils/polling.ts

@@ -1,4 +1,3 @@
-/* eslint-disable no-console */
 /**
  * @module polling
  * A high-precision, efficient, singleton polling service for scheduling periodic tasks.
@@ -13,7 +12,16 @@ interface PollingTask {
   nextRunMs: number
 }
 
-type TimeUnit = 'seconds' | 'minutes' | 'hours'
+type PollingTaskStats = {
+  count: number
+  lastStartAt: number
+  lastEndAt: number
+  lastDurationMs: number
+  maxDurationMs: number
+  lastMeta?: Record<string, unknown>
+}
+
+type TimeUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours'
 
 export class PollingService {
   private static instance: PollingService
@@ -21,6 +29,9 @@ export class PollingService {
   private timerId: NodeJS.Timeout | null = null
   private isRunning = false
   private quitListenerCleanup?: () => void
+  private activeTasks = new Map<string, number>()
+  private startAttempts = new Map<string, { count: number, lastAt: number }>()
+  private taskStats = new Map<string, PollingTaskStats>()
 
   private constructor() {
     // Private constructor to enforce singleton pattern
@@ -35,6 +46,8 @@ export class PollingService {
 
   private convertToMs(interval: number, unit: TimeUnit): number {
     switch (unit) {
+      case 'milliseconds':
+        return interval
       case 'seconds':
         return interval * 1000
       case 'minutes':
@@ -55,10 +68,17 @@ export class PollingService {
   public register(
     id: string,
     callback: () => void | Promise<void>,
-    options: { interval: number, unit: TimeUnit, runImmediately?: boolean },
+    options: {
+      interval: number
+      unit: TimeUnit
+      runImmediately?: boolean
+      initialDelayMs?: number
+    },
   ): void {
     if (this.tasks.has(id)) {
-      console.warn(`[PollingService] Task with ID '${id}' is already registered. Overwriting.`)
+      if (this.shouldVerboseLog()) {
+        console.warn(`[PollingService] Task with ID '${id}' is already registered. Overwriting.`)
+      }
     }
 
     const intervalMs = this.convertToMs(options.interval, options.unit)
@@ -67,7 +87,12 @@ export class PollingService {
       return
     }
 
-    const nextRunMs = options.runImmediately ? Date.now() : Date.now() + intervalMs
+    const now = Date.now()
+    const nextRunMs = options.runImmediately
+      ? now
+      : typeof options.initialDelayMs === 'number'
+        ? now + Math.max(0, options.initialDelayMs)
+        : now + intervalMs
 
     this.tasks.set(id, {
       id,
@@ -76,26 +101,45 @@ export class PollingService {
       nextRunMs,
     })
 
-    console.debug(`[PollingService] Task '${id}' registered to run every ${options.interval} ${options.unit}.`)
+    if (this.shouldVerboseLog()) {
+      console.debug(`[PollingService] Task '${id}' registered to run every ${options.interval} ${options.unit}.`)
+    }
 
     if (this.isRunning) {
       this._reschedule()
     }
   }
 
+  public setTaskMeta(id: string, meta: Record<string, unknown> | null): void {
+    if (!meta) return
+    const stats = this.taskStats.get(id) ?? {
+      count: 0,
+      lastStartAt: 0,
+      lastEndAt: 0,
+      lastDurationMs: 0,
+      maxDurationMs: 0,
+    }
+    stats.lastMeta = meta
+    this.taskStats.set(id, stats)
+  }
+
   /**
    * Unregisters a task, preventing it from being executed in the future.
    * @param id - The unique identifier of the task to remove.
    */
   public unregister(id: string): void {
     if (this.tasks.delete(id)) {
-      console.log(`[PollingService] Task '${id}' unregistered.`)
+      if (this.shouldVerboseLog()) {
+        console.debug(`[PollingService] Task '${id}' unregistered.`)
+      }
       if (this.isRunning) {
         this._reschedule()
       }
     }
     else {
-      console.warn(`[PollingService] Attempted to unregister a non-existent task with ID '${id}'.`)
+      if (this.shouldVerboseLog()) {
+        console.warn(`[PollingService] Attempted to unregister a non-existent task with ID '${id}'.`)
+      }
     }
   }
 
@@ -114,11 +158,13 @@ export class PollingService {
    */
   public start(): void {
     if (this.isRunning) {
-      console.warn('[PollingService] Already running, skipping start.')
+      this.recordStartAttempt()
       return
     }
     this.isRunning = true
-    console.log('[PollingService] Polling service started')
+    if (this.shouldVerboseLog()) {
+      console.log('[PollingService] Polling service started')
+    }
     this._setupQuitListener()
     this._reschedule()
   }
@@ -151,7 +197,7 @@ export class PollingService {
         }
       }
     }
-    catch (error) {
+    catch {
       // Not in Electron environment or Electron not available
       // This is fine, just skip the quit listener setup
     }
@@ -178,10 +224,14 @@ export class PollingService {
     }
 
     if (reason) {
-      console.log(`[PollingService] Stopping polling service: ${reason}`)
+      if (this.shouldVerboseLog()) {
+        console.log(`[PollingService] Stopping polling service: ${reason}`)
+      }
     }
     else {
-      console.log('[PollingService] Polling service stopped')
+      if (this.shouldVerboseLog()) {
+        console.log('[PollingService] Polling service stopped')
+      }
     }
   }
 
@@ -217,12 +267,35 @@ export class PollingService {
     if (tasksToRun.length > 0) {
       // console.debug(`[PollingService] Executing ${tasksToRun.length} tasks.`);
       for (const task of tasksToRun) {
+        const startAt = Date.now()
+        this.activeTasks.set(task.id, startAt)
         try {
           await task.callback()
         }
         catch (error) {
           console.error(`[PollingService] Error executing task '${task.id}':`, error)
         }
+        finally {
+          const endAt = Date.now()
+          const durationMs = Math.max(0, endAt - startAt)
+          const stats = this.taskStats.get(task.id) ?? {
+            count: 0,
+            lastStartAt: 0,
+            lastEndAt: 0,
+            lastDurationMs: 0,
+            maxDurationMs: 0,
+          }
+          if (this.taskStats.get(task.id)?.lastMeta) {
+            stats.lastMeta = this.taskStats.get(task.id)?.lastMeta
+          }
+          stats.count += 1
+          stats.lastStartAt = startAt
+          stats.lastEndAt = endAt
+          stats.lastDurationMs = durationMs
+          stats.maxDurationMs = Math.max(stats.maxDurationMs, durationMs)
+          this.taskStats.set(task.id, stats)
+          this.activeTasks.delete(task.id)
+        }
         // Update next run time based on its last scheduled run time, not 'now'.
         // This prevents drift if a task takes a long time to execute.
         task.nextRunMs += task.intervalMs
@@ -231,6 +304,87 @@ export class PollingService {
 
     this._reschedule()
   }
+
+  public getDiagnostics(): {
+    activeTasks: Array<{
+      id: string
+      startedAt: number
+      ageMs: number
+      intervalMs?: number
+      nextRunMs?: number
+      lastDurationMs?: number
+      maxDurationMs?: number
+      count?: number
+      lastMeta?: Record<string, unknown>
+    }>
+    recentTasks: Array<{
+      id: string
+      lastDurationMs: number
+      lastEndAt: number
+      count: number
+      maxDurationMs: number
+      intervalMs?: number
+      nextRunMs?: number
+      lastMeta?: Record<string, unknown>
+    }>
+    startAttempts: Array<{ caller: string, count: number, ageMs: number }>
+  } {
+    const now = Date.now()
+    const activeTasks = Array.from(this.activeTasks.entries())
+      .map(([id, startedAt]) => ({
+        id,
+        startedAt,
+        ageMs: Math.max(0, now - startedAt),
+        intervalMs: this.tasks.get(id)?.intervalMs,
+        nextRunMs: this.tasks.get(id)?.nextRunMs,
+        lastDurationMs: this.taskStats.get(id)?.lastDurationMs,
+        maxDurationMs: this.taskStats.get(id)?.maxDurationMs,
+        count: this.taskStats.get(id)?.count,
+        lastMeta: this.taskStats.get(id)?.lastMeta,
+      }))
+      .sort((a, b) => b.ageMs - a.ageMs)
+      .slice(0, 6)
+    const recentTasks = Array.from(this.taskStats.entries())
+      .map(([id, stat]) => ({
+        id,
+        lastDurationMs: stat.lastDurationMs,
+        lastEndAt: stat.lastEndAt,
+        count: stat.count,
+        maxDurationMs: stat.maxDurationMs,
+        intervalMs: this.tasks.get(id)?.intervalMs,
+        nextRunMs: this.tasks.get(id)?.nextRunMs,
+        lastMeta: stat.lastMeta,
+      }))
+      .sort((a, b) => b.lastEndAt - a.lastEndAt)
+      .slice(0, 6)
+    const startAttempts = Array.from(this.startAttempts.entries())
+      .map(([caller, stat]) => ({
+        caller,
+        count: stat.count,
+        ageMs: Math.max(0, now - stat.lastAt),
+      }))
+      .sort((a, b) => b.count - a.count)
+      .slice(0, 5)
+
+    return {
+      activeTasks,
+      recentTasks,
+      startAttempts,
+    }
+  }
+
+  private recordStartAttempt(): void {
+    const stack = new Error().stack
+    const caller = stack?.split('\n')[2]?.trim() ?? 'unknown'
+    const entry = this.startAttempts.get(caller) ?? { count: 0, lastAt: 0 }
+    entry.count += 1
+    entry.lastAt = Date.now()
+    this.startAttempts.set(caller, entry)
+  }
+
+  private shouldVerboseLog(): boolean {
+    return (globalThis as any).__TALEX_VERBOSE_LOGS__ === true
+  }
 }
 
 export const pollingService = PollingService.getInstance()

package/common/utils/safe-path.ts

@@ -0,0 +1,103 @@
+import pathBrowserify from 'path-browserify'
+import { hasWindow } from '../../env'
+
+const path = (() => {
+  if (hasWindow()) {
+    return pathBrowserify
+  }
+
+  const nodeRequire = typeof require === 'function' ? require : null
+  if (nodeRequire) {
+    try {
+      return nodeRequire('node:path')
+    } catch {
+      return pathBrowserify
+    }
+  }
+
+  return pathBrowserify
+})()
+
+export interface SafePathResult {
+  resolvedPath: string | null
+  error?: string
+}
+
+export interface SafePathOptions {
+  allowAbsolute?: boolean
+  allowRoot?: boolean
+}
+
+const NULL_BYTE_PATTERN = /\0/
+
+export function isAbsolutePath(value: string): boolean {
+  return path.isAbsolute(value) || path.win32.isAbsolute(value)
+}
+
+export function isSafePathSegment(value: string): boolean {
+  const trimmed = value.trim()
+  if (!trimmed || trimmed === '.' || trimmed === '..') return false
+  if (NULL_BYTE_PATTERN.test(trimmed)) return false
+  if (trimmed.includes('/') || trimmed.includes('\\')) return false
+  return true
+}
+
+export function normalizeAbsolutePath(value: string): string | null {
+  const trimmed = value.trim()
+  if (!trimmed) return null
+  if (!isAbsolutePath(trimmed)) return null
+  if (NULL_BYTE_PATTERN.test(trimmed)) return null
+  return path.normalize(trimmed)
+}
+
+export function resolveSafePath(
+  baseDir: string,
+  targetPath: string,
+  options: SafePathOptions = {}
+): SafePathResult {
+  const allowAbsolute = options.allowAbsolute ?? false
+  const allowRoot = options.allowRoot ?? false
+
+  const base = baseDir.trim()
+  const target = targetPath.trim()
+  if (!base || !target) {
+    return { resolvedPath: null, error: 'PATH_EMPTY' }
+  }
+
+  if (NULL_BYTE_PATTERN.test(target)) {
+    return { resolvedPath: null, error: 'PATH_NULL_BYTE' }
+  }
+
+  if (!allowAbsolute && isAbsolutePath(target)) {
+    return { resolvedPath: null, error: 'PATH_ABSOLUTE_NOT_ALLOWED' }
+  }
+
+  const resolvedBase = path.resolve(base)
+  const resolvedTarget = allowAbsolute && isAbsolutePath(target)
+    ? path.normalize(target)
+    : path.resolve(resolvedBase, target)
+
+  if (resolvedTarget === resolvedBase) {
+    return allowRoot
+      ? { resolvedPath: resolvedTarget }
+      : { resolvedPath: null, error: 'PATH_ROOT_NOT_ALLOWED' }
+  }
+
+  if (!resolvedTarget.startsWith(`${resolvedBase}${path.sep}`)) {
+    return { resolvedPath: null, error: 'PATH_TRAVERSAL' }
+  }
+
+  return { resolvedPath: resolvedTarget }
+}
+
+export function assertSafePath(
+  baseDir: string,
+  targetPath: string,
+  options: SafePathOptions = {}
+): string {
+  const result = resolveSafePath(baseDir, targetPath, options)
+  if (!result.resolvedPath) {
+    throw new Error(result.error ?? 'PATH_INVALID')
+  }
+  return result.resolvedPath
+}

package/common/utils/safe-shell.ts

@@ -0,0 +1,115 @@
+import type {
+  ChildProcess,
+  ExecFileOptions,
+  SpawnOptionsWithoutStdio,
+} from 'node:child_process'
+import { hasWindow } from '../../env'
+
+type ExecFileFn = typeof import('node:child_process').execFile
+type SpawnFn = typeof import('node:child_process').spawn
+
+const NULL_BYTE_PATTERN = /\0/
+const NEWLINE_PATTERN = /[\r\n]/
+
+const childProcess = (() => {
+  if (hasWindow()) {
+    return null
+  }
+
+  const nodeRequire = typeof require === 'function' ? require : null
+  if (!nodeRequire) {
+    return null
+  }
+
+  try {
+    return nodeRequire('node:child_process') as typeof import('node:child_process')
+  } catch {
+    return null
+  }
+})()
+
+const execFileImpl = childProcess?.execFile
+const spawnImpl = childProcess?.spawn
+
+function assertShellValue(value: string, label: string): string {
+  const trimmed = value.trim()
+  if (!trimmed) {
+    throw new Error(`${label}_EMPTY`)
+  }
+  if (NULL_BYTE_PATTERN.test(trimmed)) {
+    throw new Error(`${label}_NULL_BYTE`)
+  }
+  if (NEWLINE_PATTERN.test(trimmed)) {
+    throw new Error(`${label}_NEWLINE`)
+  }
+  return trimmed
+}
+
+function assertShellArg(value: string): string {
+  if (NULL_BYTE_PATTERN.test(value)) {
+    throw new Error('ARG_NULL_BYTE')
+  }
+  return value
+}
+
+function requireChildProcess(): {
+  execFile: ExecFileFn
+  spawn: SpawnFn
+} {
+  if (!execFileImpl || !spawnImpl) {
+    throw new Error('CHILD_PROCESS_UNAVAILABLE')
+  }
+
+  return {
+    execFile: execFileImpl,
+    spawn: spawnImpl,
+  }
+}
+
+export async function execFileSafe(
+  command: string,
+  args: string[] = [],
+  options: ExecFileOptions = {}
+): Promise<{ stdout: string; stderr: string }> {
+  const { execFile } = requireChildProcess()
+  const safeCommand = assertShellValue(command, 'COMMAND')
+  const safeArgs = args.map(assertShellArg)
+
+  return await new Promise((resolve, reject) => {
+    execFile(
+      safeCommand,
+      safeArgs,
+      {
+        ...options,
+        shell: false,
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(error)
+          return
+        }
+        resolve({ stdout, stderr })
+      }
+    )
+  })
+}
+
+export function spawnSafe(
+  command: string,
+  args: string[] = [],
+  options: SpawnOptionsWithoutStdio = {}
+): ChildProcess {
+  const { spawn } = requireChildProcess()
+  const safeCommand = assertShellValue(command, 'COMMAND')
+  const safeArgs = args.map(assertShellArg)
+  return spawn(safeCommand, safeArgs, { ...options, shell: false })
+}
+
+export function spawnShellCommand(
+  command: string,
+  options: SpawnOptionsWithoutStdio = {}
+): ChildProcess {
+  const { spawn } = requireChildProcess()
+  const safeCommand = assertShellValue(command, 'COMMAND')
+  return spawn(safeCommand, [], { ...options, shell: true })
+}

package/common/utils/task-queue.ts

@@ -80,7 +80,10 @@ export async function runAdaptiveTaskQueue<T>(
   )
 
   for (let index = 0; index < total; index++) {
-    await handler(items[index], index)
+    const item = items[index]
+    if (item === undefined)
+      continue
+    await handler(item, index)
 
     const processed = index + 1
     if (processed % batchSize === 0 && processed < total) {

package/core-box/builder/tuff-builder.ts

@@ -578,7 +578,6 @@ class TuffSearchResultBuilder {
   }
 
   public setSortStats(stats: any[]): this {
-    // @ts-ignore
     this.result.sort_stats = stats
     return this
   }

package/core-box/index.ts

@@ -1,8 +1,8 @@
 export * from './builder/index'
 export * from './preview/index'
+export * from './recommendation'
 /**
  * Core Box Package
  * Search box core functionality package
  */
 export * from './tuff/index'
-export * from './recommendation'

package/core-box/recommendation.ts

@@ -51,10 +51,47 @@ export interface ScoredItem {
   sourceId: string
   itemId: string
   score: number
-  source: 'frequent' | 'time-based' | 'recent' | 'trending' | 'context'
+  source: 'frequent' | 'time-based' | 'recent' | 'trending' | 'context' | 'plugin'
   reason?: string
 }
 
+/**
+ * Candidate item returned by a plugin recommend provider.
+ * Unlike internal candidates, these do not require usageStats.
+ */
+export interface PluginRecommendCandidate {
+  /** Provider ID (auto-filled from provider.id) */
+  providerId?: string
+  /** Unique item ID */
+  id: string
+  /** Display title */
+  title: string
+  /** Subtitle / description */
+  subtitle?: string
+  /** Icon configuration */
+  icon?: { type: string; value: string }
+  /** Priority 0-100, higher = more prominent */
+  priority?: number
+  /** Action key passed back to the plugin */
+  action: string
+  /** Additional data */
+  data?: Record<string, unknown>
+}
+
+/**
+ * Provider interface for plugins to supply custom recommendations.
+ */
+export interface RecommendProvider {
+  /** Unique provider ID */
+  id: string
+  /** Display name */
+  name: string
+  /** Whether this provider can supply recommendations for the given context */
+  canProvide(context: ContextSignal): boolean
+  /** Return recommendation candidates */
+  getCandidates(context: ContextSignal): PluginRecommendCandidate[] | Promise<PluginRecommendCandidate[]>
+}
+
 /**
  * Recommendation badge display configuration for UI rendering.
  */

package/core-box/tuff/tuff-dsl.ts

@@ -380,6 +380,7 @@ export interface TuffCustomRender {
 
 /**
  * Icon definition
+ * @deprecated
  *
  * @description
  * Unified icon type supporting only ITuffIcon object format
@@ -1369,6 +1370,8 @@ export interface TuffContainerLayout {
 export interface TuffSectionMeta {
   /** 是否为智能推荐分组 */
   intelligence?: boolean
+  /** 是否为置顶分组 */
+  pinned?: boolean
   /** 扩展字段 */
   [key: string]: unknown
 }
@@ -1420,6 +1423,18 @@ export interface IProviderActivate {
   icon?: TuffIcon
   time?: number
   meta?: Record<string, any>
+  /**
+   * Whether the results area should be hidden when this provider is active.
+   * - true: Hide results (webcontent mode - plugin UI view is attached)
+   * - false/undefined: Show results (push mode - plugin pushes items to list)
+   */
+  hideResults?: boolean
+  /**
+   * Whether the input box should be shown when this provider is active.
+   * - true: Show input (feature accepts input via acceptedInputTypes or allowInput)
+   * - false/undefined: Hide input in webcontent mode, show in push mode
+   */
+  showInput?: boolean
 }
 
 /**
@@ -1482,6 +1497,23 @@ export interface ISearchProvider<C> {
    */
   readonly supportedInputTypes?: TuffInputType[]
 
+  /**
+   * Search priority layer
+   * @description Determines when this provider's results are returned:
+   * - 'fast': Results are returned immediately with the first batch (blocking)
+   * - 'deferred': Results are appended asynchronously after fast layer completes
+   * @default 'deferred'
+   */
+  readonly priority?: 'fast' | 'deferred'
+
+  /**
+   * Expected search duration in milliseconds
+   * @description Used for sorting providers within the same layer and timeout estimation.
+   * Providers with lower expected duration run first within their layer.
+   * @default 1000
+   */
+  readonly expectedDuration?: number
+
   /**
    * Core search method (PULL mode).
    * The engine calls this method to get results from the provider.

package/electron/download-manager.ts

@@ -1,6 +1,9 @@
 import path from 'node:path'
 import { net } from 'electron'
 import fse from 'fs-extra'
+import { getLogger } from '../common/logger'
+
+const downloadLog = getLogger('download-manager')
 
 interface DownloadItem {
   url: string
@@ -52,16 +55,16 @@ export class DownloadManager {
     const item = this.downloadQueue.shift()!
 
     try {
-      console.log(`[DownloadManager] Starting to download ${item.filename} from ${item.url}`)
+      downloadLog.info(`Starting to download ${item.filename} from ${item.url}`)
       const filePath = await this.downloadFile(item.url, item.filename)
-      console.log(`[DownloadManager] Download ${item.filename} completed`)
+      downloadLog.info(`Download ${item.filename} completed`)
 
       if (item.apply) {
         item.apply(filePath)
       }
     }
     catch (error) {
-      console.error(`[DownloadManager] Download ${item.filename} failed:`, error)
+      downloadLog.error(`Download ${item.filename} failed`, { error })
     }
 
     this.processQueue()
@@ -78,10 +81,10 @@ export class DownloadManager {
       const request = net.request(url)
       const filePath = this.basePath ? path.join(this.basePath, filename) : filename
 
-      console.log(`[DownloadManager] File download request sent for ${filename}.`)
+      downloadLog.info(`File download request sent for ${filename}.`)
 
       request.addListener('error', (error) => {
-        console.error(`[DownloadManager] Download request error for ${filename}:`, error)
+        downloadLog.error(`Download request error for ${filename}`, { error })
         reject(error)
       })
 
@@ -89,12 +92,12 @@ export class DownloadManager {
         fse.createFileSync(filePath)
 
         response.addListener('data', (chunk: any) => {
-          console.log(`[DownloadManager] Downloading ${filename}...`)
+          downloadLog.debug(`Downloading ${filename}...`)
           fse.appendFile(filePath, chunk, 'utf8')
         })
 
         response.addListener('end', () => {
-          console.log(`[DownloadManager] Download ${filename} finished.`)
+          downloadLog.info(`Download ${filename} finished.`)
           resolve(filePath)
         })
       })