@talex-touch/utils 1.0.40 → 1.0.44

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
@@ -803,6 +804,65 @@ export interface TuffContext {
   tags?: string[]
 }
 
+// ==================== Footer Hints 配置 ====================
+
+/**
+ * Footer hint 单项配置
+ */
+export interface TuffFooterHintItem {
+  /** 快捷键显示文本 */
+  key: string
+  /** 提示标签 */
+  label: string
+  /** 是否显示此提示 */
+  visible?: boolean
+  /** 触发的事件名称 */
+  event?: string
+  /** 事件携带的数据 */
+  eventData?: Record<string, unknown>
+}
+
+/**
+ * Footer hints 配置
+ * @description 控制 CoreBox 底部快捷键提示的显示和行为
+ */
+export interface TuffFooterHints {
+  /**
+   * 主操作提示（回车键）
+   * @description 自定义回车键的文案，如 "发送"、"执行"、"打开" 等
+   */
+  primary?: {
+    /** 自定义标签文案 */
+    label?: string
+    /** 是否显示 */
+    visible?: boolean
+  }
+
+  /**
+   * 辅助操作提示（Meta+K）
+   * @description 控制 Meta+K 快捷键的显示和行为
+   */
+  secondary?: {
+    /** 自定义标签文案 */
+    label?: string
+    /** 是否显示，默认 false（隐藏） */
+    visible?: boolean
+    /** 触发的事件名称 */
+    event?: string
+    /** 事件携带的数据 */
+    eventData?: Record<string, unknown>
+  }
+
+  /**
+   * 快速选择提示（Meta+1-0）
+   * @description 控制快速选择快捷键的显示
+   */
+  quickSelect?: {
+    /** 是否显示，默认根据场景自动判断 */
+    visible?: boolean
+  }
+}
+
 // ==================== 扩展元数据 ====================
 
 /**
@@ -1030,6 +1090,12 @@ export interface TuffMeta {
    * @warning 不建议添加太多关键词（建议 <= 10），过多会影响搜索性能
    */
   keywords?: string[]
+
+  /**
+   * Footer hints 配置
+   * @description 控制 CoreBox 底部快捷键提示的显示和行为
+   */
+  footerHints?: TuffFooterHints
 }
 
 // ==================== 前端展示结构 ====================
@@ -1304,6 +1370,8 @@ export interface TuffContainerLayout {
 export interface TuffSectionMeta {
   /** 是否为智能推荐分组 */
   intelligence?: boolean
+  /** 是否为置顶分组 */
+  pinned?: boolean
   /** 扩展字段 */
   [key: string]: unknown
 }
@@ -1355,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
 }
 
 /**
@@ -1417,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)
         })
       })

package/electron/env-tool.ts

@@ -1,6 +1,8 @@
 import type { ExecException } from 'node:child_process'
-import { exec } from 'node:child_process'
 import { platform } from 'node:process'
+import { execFileSafe } from '../common/utils/safe-shell'
+
+type ExecError = { error?: unknown }
 
 export interface IGlobalPkgResult {
   exist: boolean
@@ -9,53 +11,53 @@ export interface IGlobalPkgResult {
   version?: string
 }
 
-export function checkGlobalPackageExist(packageName: string): Promise<IGlobalPkgResult> {
-  return new Promise((resolve, reject) => {
-    exec(`npm list -g ${packageName}`, (error, stdout, stderr) => {
-      if (error) {
-        reject({
-          exits: false,
-          error,
-        })
-        return
-      }
-      if (stderr) {
-        reject({
-          exits: false,
-          error: stderr,
-        })
-        return
-      }
+export async function checkGlobalPackageExist(packageName: string): Promise<IGlobalPkgResult> {
+  const name = packageName.trim()
+  if (!name) {
+    throw new Error('Package name is required')
+  }
 
-      const lines = stdout.split('\n')
-      const lastLine = lines[lines.length - 3]
-      const match = lastLine.match(/(\S+)@(\S+)/)
-      if (match) {
-        resolve({
-          exist: true,
-          name: match[1],
-          version: match[2],
-        } as IGlobalPkgResult)
-        return
-      }
+  try {
+    const { stdout, stderr } = await execFileSafe('npm', ['list', '-g', name])
+    if (stderr) {
+      const stderrError = Object.assign(new Error('Failed to check global package'), {
+        error: stderr
+      })
+      throw stderrError
+    }
 
-      resolve({
-        exist: false,
-      } as IGlobalPkgResult)
+    const lines = stdout.split('\n')
+    const lastLine = lines[lines.length - 3]
+    const match = lastLine.match(/([^@\s]+)@(\S+)/)
+    if (match) {
+      return {
+        exist: true,
+        name: match[1],
+        version: match[2]
+      } as IGlobalPkgResult
+    }
+
+    return {
+      exist: false
+    } as IGlobalPkgResult
+  } catch (error) {
+    const execError = Object.assign(new Error('Failed to check global package'), {
+      error: error as ExecError
     })
-  })
+    return Promise.reject(execError)
+  }
 }
 
 // Check npm version
 export function getNpmVersion(): Promise<string | null> {
-  return new Promise((resolve) => {
-    exec(`npm --version`, (error, stdout, stderr) => {
-      if (error || stderr)
-        resolve(null)
-
-      resolve(stdout.trim())
+  return execFileSafe('npm', ['--version'])
+    .then(({ stdout, stderr }) => {
+      if (stderr) {
+        return null
+      }
+      return stdout.trim()
     })
-  })
+    .catch(() => null)
 }
 
 export interface OSAdapter<R, T> {

package/electron/index.ts

@@ -1,3 +1,2 @@
 export * from './download-manager'
 export * from './env-tool'
-

package/env/index.ts

@@ -0,0 +1,156 @@
+export const NEXUS_BASE_URL = 'https://tuff.tagzxia.com'
+
+export interface EnvLike {
+  [key: string]: unknown
+}
+
+function getProcess(): any {
+  return (globalThis as any)?.process
+}
+
+function readGlobalEnv(): Record<string, string | undefined> {
+  const g: any = globalThis as any
+  const fromGlobal = g.__TUFF_ENV && typeof g.__TUFF_ENV === 'object' ? g.__TUFF_ENV : null
+  const record: Record<string, string | undefined> = {}
+
+  if (fromGlobal) {
+    for (const [k, v] of Object.entries(fromGlobal)) {
+      if (typeof v === 'string') {
+        record[k] = v
+      }
+      else if (typeof v === 'number' || typeof v === 'boolean') {
+        record[k] = String(v)
+      }
+    }
+  }
+
+  const p: any = getProcess()
+  if (p && p.env && typeof p.env === 'object') {
+    for (const [k, v] of Object.entries(p.env)) {
+      if (typeof v === 'string') {
+        record[k] = v
+      }
+      else if (typeof v === 'number' || typeof v === 'boolean') {
+        record[k] = String(v)
+      }
+    }
+  }
+
+  return record
+}
+
+export function setRuntimeEnv(env: Record<string, string | undefined>): void {
+  const g: any = globalThis as any
+  const normalized: Record<string, string | undefined> = {}
+  for (const [k, v] of Object.entries(env ?? {})) {
+    if (typeof v === 'string') {
+      normalized[k] = v
+    }
+    else if (typeof v === 'number' || typeof v === 'boolean') {
+      normalized[k] = String(v)
+    }
+  }
+  g.__TUFF_ENV = { ...(g.__TUFF_ENV || {}), ...normalized }
+}
+
+export function getEnv(key: string): string | undefined {
+  return readGlobalEnv()[key]
+}
+
+export function getEnvOrDefault(key: string, fallback: string): string {
+  return getEnv(key) ?? fallback
+}
+
+export function getBooleanEnv(key: string, fallback = false): boolean {
+  const raw = getEnv(key)
+  if (raw === undefined)
+    return fallback
+  if (raw === '1' || raw === 'true')
+    return true
+  if (raw === '0' || raw === 'false')
+    return false
+  return fallback
+}
+
+export function hasWindow(): boolean {
+  return typeof window !== 'undefined'
+}
+
+export function hasDocument(): boolean {
+  return typeof document !== 'undefined'
+}
+
+export function hasNavigator(): boolean {
+  return typeof navigator !== 'undefined'
+}
+
+export function isBrowserRuntime(): boolean {
+  return hasWindow() && hasDocument()
+}
+
+export function isNodeRuntime(): boolean {
+  const proc: any = getProcess()
+  return typeof proc !== 'undefined'
+    && Boolean(proc?.versions?.node)
+}
+
+export function isElectronRuntime(): boolean {
+  const proc: any = getProcess()
+  return Boolean(proc?.versions?.electron)
+}
+
+export function isElectronRenderer(): boolean {
+  const proc: any = getProcess()
+  return Boolean(proc?.versions?.electron)
+    && proc?.type === 'renderer'
+}
+
+export function isElectronMain(): boolean {
+  const proc: any = getProcess()
+  return Boolean(proc?.versions?.electron)
+    && (proc?.type === 'browser' || !proc?.type)
+}
+
+export function isDevEnv(): boolean {
+  const nodeEnv = getEnv('NODE_ENV')
+  if (nodeEnv) {
+    return nodeEnv === 'development' || nodeEnv === 'test'
+  }
+  const mode = getEnv('MODE') || getEnv('VITE_MODE')
+  if (mode) {
+    return mode === 'development'
+  }
+  return getBooleanEnv('DEV', false)
+}
+
+export function isProdEnv(): boolean {
+  const nodeEnv = getEnv('NODE_ENV')
+  if (nodeEnv) {
+    return nodeEnv === 'production'
+  }
+  const mode = getEnv('MODE') || getEnv('VITE_MODE')
+  if (mode) {
+    return mode === 'production'
+  }
+  return getBooleanEnv('PROD', false)
+}
+
+export function normalizeBaseUrl(input: string): string {
+  return input.replace(/\/$/, '')
+}
+
+export function getTuffBaseUrl(): string {
+  return normalizeBaseUrl(getEnvOrDefault('VITE_NEXUS_URL', NEXUS_BASE_URL))
+}
+
+export function getTelemetryApiBase(): string {
+  const url = normalizeBaseUrl(getEnvOrDefault('NEXUS_API_BASE', NEXUS_BASE_URL))
+  if (!url) {
+    throw new Error('Telemetry API base URL is not configured')
+  }
+  return url
+}
+
+export function getTpexApiBase(): string {
+  return normalizeBaseUrl(getEnvOrDefault('TPEX_API_BASE', NEXUS_BASE_URL))
+}

package/eslint.config.js

@@ -0,0 +1,55 @@
+const antfu = require('@antfu/eslint-config').default
+
+module.exports = antfu(
+  {
+    type: 'lib',
+    typescript: true,
+    stylistic: false,
+    unicorn: false,
+    test: false,
+    markdown: false,
+    regexp: false,
+    ignores: [
+      'plugin/sdk/examples/**',
+    ],
+  },
+  {
+    rules: {
+      'antfu/if-newline': 'off',
+      'jsdoc/check-param-names': 'off',
+      'jsdoc/empty-tags': 'off',
+      'import/consistent-type-specifier-style': 'off',
+      'import/first': 'off',
+      'node/prefer-global/buffer': 'off',
+      'node/prefer-global/process': 'off',
+      'no-console': 'off',
+      'no-useless-return': 'off',
+      'perfectionist/sort-exports': 'off',
+      'perfectionist/sort-imports': 'off',
+      'perfectionist/sort-named-exports': 'off',
+      'perfectionist/sort-named-imports': 'off',
+      'prefer-promise-reject-errors': 'off',
+      'test/prefer-lowercase-title': 'off',
+      'ts/consistent-type-definitions': 'off',
+      'ts/ban-ts-comment': 'off',
+      'ts/explicit-function-return-type': 'off',
+      'ts/method-signature-style': 'off',
+      'ts/no-namespace': 'off',
+      'ts/no-empty-object-type': 'off',
+      'ts/no-require-imports': 'off',
+      'ts/no-unsafe-function-type': 'off',
+      'ts/no-use-before-define': 'off',
+      'unicorn/escape-case': 'off',
+      'unicorn/new-for-builtins': 'off',
+      'unicorn/no-instanceof-builtins': 'off',
+      'unicorn/no-new-array': 'off',
+      'vars-on-top': 'off',
+    },
+  },
+  {
+    files: ['plugin/channel.ts'],
+    rules: {
+      'no-eval': 'off',
+    },
+  },
+)

package/i18n/index.ts

@@ -0,0 +1,62 @@
+/**
+ * I18n Utilities
+ *
+ * Shared i18n utilities for backend-frontend communication.
+ *
+ * ## Backend Usage (Main Process)
+ * ```typescript
+ * import { i18nMsg, DevServerKeys } from '@talex-touch/utils/i18n'
+ *
+ * // Send i18n message to frontend
+ * win.webContents.send('notification', {
+ *   message: i18nMsg(DevServerKeys.DISCONNECTED)
+ * })
+ * ```
+ *
+ * ## Frontend Usage (Renderer)
+ * ```typescript
+ * import { resolveI18nMessage, i18nResolver } from '@talex-touch/utils/i18n'
+ *
+ * // Set locale
+ * i18nResolver.setLocale('zh')
+ *
+ * // Resolve message
+ * const text = resolveI18nMessage('$i18n:devServer.disconnected')
+ * // => '开发服务器已断开'
+ * ```
+ */
+
+// Locale data
+export { default as enMessages } from './locales/en.json'
+
+export { default as zhMessages } from './locales/zh.json'
+
+// Message keys and utilities for backend
+export {
+  type DevServerKey,
+  DevServerKeys,
+  type FlowTransferKey,
+  FlowTransferKeys,
+  I18N_PREFIX,
+  i18nMsg,
+  i18nMsgWithParams,
+  isI18nMessage,
+  MessageKeys,
+  parseI18nMessage,
+  type PluginKey,
+  PluginKeys,
+  type SystemKey,
+  SystemKeys,
+  type WidgetKey,
+  WidgetKeys,
+} from './message-keys'
+// Resolver for frontend
+export {
+  createI18nMessage,
+  I18nResolver,
+  i18nResolver,
+  type MessageLocale,
+  type Messages,
+  resolveI18nMessage,
+  useI18nResolver,
+} from './resolver'