@talex-touch/utils 1.0.39 → 1.0.42

package/plugin/providers/npm-provider.ts

@@ -0,0 +1,213 @@
+import type { IManifest } from '..'
+import type {
+  PluginInstallRequest,
+  PluginInstallResult,
+  PluginProvider,
+  PluginProviderContext,
+} from './types'
+import { PluginProviderType } from './types'
+
+const NPM_REGISTRY = 'https://registry.npmjs.org'
+const TUFF_PLUGIN_PREFIX = 'tuff-plugin-'
+const TUFF_PLUGIN_SCOPE = '@tuff/'
+
+export interface NpmPackageInfo {
+  name: string
+  version: string
+  description?: string
+  author?: string | { name: string, email?: string }
+  main?: string
+  keywords?: string[]
+  dist: {
+    tarball: string
+    shasum: string
+    integrity?: string
+  }
+  tuff?: {
+    icon?: string
+    activationKeywords?: string[]
+  }
+}
+
+export interface NpmPackageVersions {
+  name: string
+  'dist-tags': {
+    latest: string
+    [tag: string]: string
+  }
+  versions: Record<string, NpmPackageInfo>
+}
+
+/**
+ * Parse NPM source string to extract package name and optional version
+ * Formats:
+ * - "npm:package-name"
+ * - "npm:package-name@version"
+ * - "npm:@scope/package-name"
+ * - "npm:@scope/package-name@version"
+ * - "tuff-plugin-xxx" (when hintType is NPM)
+ * - "@tuff/xxx" (when hintType is NPM)
+ */
+function parseNpmSource(source: string): { packageName: string, version?: string } | null {
+  const npmMatch = source.match(/^npm:(@?[a-z0-9][\w\-.]*(?:\/[a-z0-9][\w\-.]*)?)(?:@(.+))?$/i)
+  if (npmMatch) {
+    return { packageName: npmMatch[1], version: npmMatch[2] }
+  }
+
+  const scopedMatch = source.match(/^(@tuff\/[a-z0-9][\w\-.]*)(?:@(.+))?$/i)
+  if (scopedMatch) {
+    return { packageName: scopedMatch[1], version: scopedMatch[2] }
+  }
+
+  const prefixMatch = source.match(/^(tuff-plugin-[a-z0-9][\w\-.]*)(?:@(.+))?$/i)
+  if (prefixMatch) {
+    return { packageName: prefixMatch[1], version: prefixMatch[2] }
+  }
+
+  return null
+}
+
+/**
+ * Check if a package name looks like a Tuff plugin
+ */
+function isTuffPluginPackage(name: string): boolean {
+  return name.startsWith(TUFF_PLUGIN_PREFIX) || name.startsWith(TUFF_PLUGIN_SCOPE)
+}
+
+export class NpmProvider implements PluginProvider {
+  readonly type = PluginProviderType.NPM
+  private registry: string
+
+  constructor(registry: string = NPM_REGISTRY) {
+    this.registry = registry.replace(/\/$/, '')
+  }
+
+  canHandle(request: PluginInstallRequest): boolean {
+    if (request.hintType === PluginProviderType.NPM) {
+      return parseNpmSource(request.source) !== null
+    }
+
+    if (request.source.startsWith('npm:')) {
+      return true
+    }
+
+    const parsed = parseNpmSource(request.source)
+    return parsed !== null && isTuffPluginPackage(parsed.packageName)
+  }
+
+  async install(
+    request: PluginInstallRequest,
+    context?: PluginProviderContext,
+  ): Promise<PluginInstallResult> {
+    const parsed = parseNpmSource(request.source)
+    if (!parsed) {
+      throw new Error(`Invalid NPM source format: ${request.source}`)
+    }
+
+    const { packageName, version } = parsed
+    const packageInfo = await this.getPackageInfo(packageName, version)
+
+    if (!packageInfo) {
+      throw new Error(`Package not found: ${packageName}`)
+    }
+
+    const tarballUrl = packageInfo.dist.tarball
+    const downloadRes = await fetch(tarballUrl)
+    if (!downloadRes.ok) {
+      throw new Error(`Failed to download package: ${downloadRes.statusText}`)
+    }
+
+    const arrayBuffer = await downloadRes.arrayBuffer()
+    const tempDir = context?.tempDir ?? '/tmp'
+    const safePackageName = packageName.replace(/[@/]/g, '-')
+    const fileName = `${safePackageName}-${packageInfo.version}.tgz`
+    const filePath = `${tempDir}/${fileName}`
+
+    if (typeof globalThis.process !== 'undefined') {
+      const fs = await import('node:fs/promises')
+      await fs.writeFile(filePath, Buffer.from(arrayBuffer))
+    }
+
+    const authorName = typeof packageInfo.author === 'string'
+      ? packageInfo.author
+      : packageInfo.author?.name ?? 'Unknown'
+
+    const manifest: IManifest = {
+      id: packageInfo.name,
+      name: packageInfo.name.replace(TUFF_PLUGIN_PREFIX, '').replace(TUFF_PLUGIN_SCOPE, ''),
+      version: packageInfo.version,
+      description: packageInfo.description ?? '',
+      author: authorName,
+      main: packageInfo.main ?? 'index.js',
+      icon: packageInfo.tuff?.icon,
+      activationKeywords: packageInfo.tuff?.activationKeywords ?? packageInfo.keywords,
+    }
+
+    return {
+      provider: PluginProviderType.NPM,
+      filePath,
+      official: packageName.startsWith(TUFF_PLUGIN_SCOPE),
+      manifest,
+      metadata: {
+        packageName: packageInfo.name,
+        version: packageInfo.version,
+        tarball: tarballUrl,
+        shasum: packageInfo.dist.shasum,
+        integrity: packageInfo.dist.integrity,
+      },
+    }
+  }
+
+  /**
+   * Get package info from npm registry
+   */
+  async getPackageInfo(packageName: string, version?: string): Promise<NpmPackageInfo | null> {
+    const encodedName = encodeURIComponent(packageName).replace('%40', '@')
+    const res = await fetch(`${this.registry}/${encodedName}`)
+
+    if (!res.ok) {
+      if (res.status === 404) return null
+      throw new Error(`Failed to fetch package info: ${res.statusText}`)
+    }
+
+    const data: NpmPackageVersions = await res.json()
+    const targetVersion = version ?? data['dist-tags'].latest
+
+    return data.versions[targetVersion] ?? null
+  }
+
+  /**
+   * Search for Tuff plugins on npm
+   */
+  async searchPlugins(keyword?: string): Promise<NpmPackageInfo[]> {
+    const searchTerms = [
+      `keywords:tuff-plugin`,
+      keyword ? `${keyword}` : '',
+    ].filter(Boolean).join('+')
+
+    const res = await fetch(
+      `${this.registry}/-/v1/search?text=${encodeURIComponent(searchTerms)}&size=100`,
+    )
+
+    if (!res.ok) {
+      throw new Error(`Failed to search packages: ${res.statusText}`)
+    }
+
+    const data = await res.json() as {
+      objects: Array<{ package: NpmPackageInfo }>
+    }
+
+    return data.objects
+      .map(obj => obj.package)
+      .filter(pkg => isTuffPluginPackage(pkg.name))
+  }
+
+  /**
+   * List all available Tuff plugins from npm
+   */
+  async listPlugins(): Promise<NpmPackageInfo[]> {
+    return this.searchPlugins()
+  }
+}
+
+export const npmProvider = new NpmProvider()

package/plugin/providers/tpex-provider.ts

@@ -0,0 +1,283 @@
+import type { IManifest } from '..'
+import type {
+  PluginInstallRequest,
+  PluginInstallResult,
+  PluginProvider,
+  PluginProviderContext,
+} from './types'
+import { PluginProviderType } from './types'
+
+const DEFAULT_TPEX_API = 'https://tuff.tagzxia.com'
+
+/**
+ * Check if source is a .tpex file path or URL
+ */
+function isTpexFile(source: string): boolean {
+  return source.trim().toLowerCase().endsWith('.tpex')
+}
+
+/**
+ * Check if source is a remote URL
+ */
+function isRemoteUrl(source: string): boolean {
+  return /^https?:\/\//i.test(source)
+}
+
+export interface TpexPluginInfo {
+  id: string
+  slug: string
+  name: string
+  summary: string
+  category: string
+  installs: number
+  homepage?: string | null
+  isOfficial: boolean
+  badges: string[]
+  author?: { name: string, avatarColor?: string } | null
+  iconUrl?: string | null
+  latestVersion?: {
+    id: string
+    version: string
+    channel: string
+    packageUrl: string
+    packageSize: number
+    manifest?: Record<string, unknown> | null
+    changelog?: string | null
+  }
+}
+
+export interface TpexListResponse {
+  plugins: TpexPluginInfo[]
+  total: number
+}
+
+export interface TpexDetailResponse {
+  plugin: TpexPluginInfo & {
+    versions?: Array<{
+      id: string
+      version: string
+      channel: string
+      packageUrl: string
+      packageSize: number
+      manifest?: Record<string, unknown> | null
+      changelog?: string | null
+    }>
+  }
+}
+
+/**
+ * Parse TPEX source string to extract slug and optional version
+ * Formats: "tpex:slug", "tpex:slug@version", "slug" (when hintType is TPEX)
+ */
+function parseTpexSource(source: string): { slug: string, version?: string } | null {
+  const tpexMatch = source.match(/^tpex:([a-z0-9][a-z0-9\-_.]{1,62}[a-z0-9])(?:@(.+))?$/i)
+  if (tpexMatch) {
+    return { slug: tpexMatch[1], version: tpexMatch[2] }
+  }
+
+  const slugMatch = source.match(/^([a-z0-9][a-z0-9\-_.]{1,62}[a-z0-9])(?:@(.+))?$/i)
+  if (slugMatch) {
+    return { slug: slugMatch[1], version: slugMatch[2] }
+  }
+
+  return null
+}
+
+export class TpexProvider implements PluginProvider {
+  readonly type = PluginProviderType.TPEX
+  private apiBase: string
+
+  constructor(apiBase: string = DEFAULT_TPEX_API) {
+    this.apiBase = apiBase.replace(/\/$/, '')
+  }
+
+  canHandle(request: PluginInstallRequest): boolean {
+    // Handle .tpex file paths (local or remote URL)
+    if (isTpexFile(request.source)) {
+      return true
+    }
+
+    if (request.hintType === PluginProviderType.TPEX) {
+      return parseTpexSource(request.source) !== null
+    }
+    return request.source.startsWith('tpex:')
+  }
+
+  async install(
+    request: PluginInstallRequest,
+    context?: PluginProviderContext,
+  ): Promise<PluginInstallResult> {
+    // Handle .tpex file directly (local path or remote URL)
+    if (isTpexFile(request.source)) {
+      return this.installFromFile(request, context)
+    }
+
+    // Handle tpex:slug format - fetch from API
+    return this.installFromRegistry(request, context)
+  }
+
+  /**
+   * Install from a .tpex file (local path or remote URL)
+   */
+  private async installFromFile(
+    request: PluginInstallRequest,
+    context?: PluginProviderContext,
+  ): Promise<PluginInstallResult> {
+    let filePath = request.source
+    let arrayBuffer: ArrayBuffer | undefined
+
+    if (isRemoteUrl(request.source)) {
+      // Download remote .tpex file
+      const downloadRes = await fetch(request.source)
+      if (!downloadRes.ok) {
+        throw new Error(`Failed to download TPEX file: ${downloadRes.statusText}`)
+      }
+
+      arrayBuffer = await downloadRes.arrayBuffer()
+      const tempDir = context?.tempDir ?? '/tmp'
+      const fileName = `tpex-${Date.now()}.tpex`
+      filePath = `${tempDir}/${fileName}`
+
+      if (typeof globalThis.process !== 'undefined') {
+        const fs = await import('node:fs/promises')
+        await fs.writeFile(filePath, Buffer.from(arrayBuffer))
+      }
+    }
+
+    // For local files, just return the path - manifest extraction happens in core-app
+    return {
+      provider: PluginProviderType.TPEX,
+      filePath,
+      official: false,
+      metadata: {
+        sourceType: 'file',
+        originalSource: request.source,
+      },
+    }
+  }
+
+  /**
+   * Install from TPEX registry (tpex:slug format)
+   */
+  private async installFromRegistry(
+    request: PluginInstallRequest,
+    context?: PluginProviderContext,
+  ): Promise<PluginInstallResult> {
+    const parsed = parseTpexSource(request.source)
+    if (!parsed) {
+      throw new Error(`Invalid TPEX source format: ${request.source}`)
+    }
+
+    const { slug, version } = parsed
+
+    const detailRes = await fetch(`${this.apiBase}/api/market/plugins/${slug}`)
+    if (!detailRes.ok) {
+      if (detailRes.status === 404) {
+        throw new Error(`Plugin not found: ${slug}`)
+      }
+      throw new Error(`Failed to fetch plugin details: ${detailRes.statusText}`)
+    }
+
+    const detail: TpexDetailResponse = await detailRes.json()
+    const plugin = detail.plugin
+
+    let targetVersion = plugin.latestVersion
+    if (version && plugin.versions) {
+      targetVersion = plugin.versions.find(v => v.version === version) ?? targetVersion
+    }
+
+    if (!targetVersion?.packageUrl) {
+      throw new Error(`No downloadable version found for plugin: ${slug}`)
+    }
+
+    const downloadUrl = targetVersion.packageUrl.startsWith('http')
+      ? targetVersion.packageUrl
+      : `${this.apiBase}${targetVersion.packageUrl}`
+
+    const downloadRes = await fetch(downloadUrl)
+    if (!downloadRes.ok) {
+      throw new Error(`Failed to download plugin package: ${downloadRes.statusText}`)
+    }
+
+    const arrayBuffer = await downloadRes.arrayBuffer()
+    const tempDir = context?.tempDir ?? '/tmp'
+    const fileName = `${slug}-${targetVersion.version}.tpex`
+    const filePath = `${tempDir}/${fileName}`
+
+    if (typeof globalThis.process !== 'undefined') {
+      const fs = await import('node:fs/promises')
+      await fs.writeFile(filePath, Buffer.from(arrayBuffer))
+    }
+
+    const manifest: IManifest | undefined = targetVersion.manifest
+      ? {
+          id: plugin.slug,
+          name: plugin.name,
+          version: targetVersion.version,
+          description: plugin.summary,
+          author: plugin.author?.name ?? 'Unknown',
+          main: (targetVersion.manifest as Record<string, unknown>).main as string ?? 'index.js',
+          icon: plugin.iconUrl ?? undefined,
+          ...targetVersion.manifest,
+        }
+      : undefined
+
+    return {
+      provider: PluginProviderType.TPEX,
+      filePath,
+      official: plugin.isOfficial,
+      manifest,
+      metadata: {
+        sourceType: 'registry',
+        slug: plugin.slug,
+        version: targetVersion.version,
+        channel: targetVersion.channel,
+        packageSize: targetVersion.packageSize,
+        installs: plugin.installs,
+      },
+    }
+  }
+
+  /**
+   * List all available plugins from TPEX registry
+   */
+  async listPlugins(): Promise<TpexPluginInfo[]> {
+    const res = await fetch(`${this.apiBase}/api/market/plugins`)
+    if (!res.ok) {
+      throw new Error(`Failed to fetch plugin list: ${res.statusText}`)
+    }
+
+    const data: TpexListResponse = await res.json()
+    return data.plugins
+  }
+
+  /**
+   * Get plugin details by slug
+   */
+  async getPlugin(slug: string): Promise<TpexDetailResponse['plugin'] | null> {
+    const res = await fetch(`${this.apiBase}/api/market/plugins/${slug}`)
+    if (!res.ok) {
+      if (res.status === 404) return null
+      throw new Error(`Failed to fetch plugin: ${res.statusText}`)
+    }
+
+    const data: TpexDetailResponse = await res.json()
+    return data.plugin
+  }
+
+  /**
+   * Search plugins by keyword
+   */
+  async searchPlugins(keyword: string): Promise<TpexPluginInfo[]> {
+    const plugins = await this.listPlugins()
+    const lowerKeyword = keyword.toLowerCase()
+
+    return plugins.filter(plugin =>
+      plugin.name.toLowerCase().includes(lowerKeyword)
+      || plugin.slug.toLowerCase().includes(lowerKeyword)
+      || plugin.summary.toLowerCase().includes(lowerKeyword),
+    )
+  }
+}
+
+export const tpexProvider = new TpexProvider()

package/plugin/providers/tpex-types.ts

@@ -0,0 +1,34 @@
+/**
+ * Metadata extracted from a .tpex package file
+ */
+export interface TpexMetadata {
+  readmeMarkdown?: string | null
+  manifest?: Record<string, unknown> | null
+}
+
+/**
+ * Result of package preview operation
+ */
+export interface TpexPackagePreviewResult {
+  manifest: Record<string, unknown> | null
+  readmeMarkdown: string | null
+}
+
+/**
+ * Extracted manifest fields from tpex package
+ */
+export interface TpexExtractedManifest {
+  id?: string
+  name?: string
+  description?: string
+  version?: string
+  homepage?: string
+  changelog?: string
+  channel?: string
+  category?: string
+  icon?: {
+    type?: string
+    value?: string
+  }
+  [key: string]: unknown
+}

package/plugin/sdk/README.md

@@ -66,6 +66,53 @@ const unsubscribe = plugin.feature.onInputChange((input) => {
 
 // 取消监听
 unsubscribe()
+
+// 监听键盘事件（UI View 模式下）
+const unsubscribeKey = plugin.feature.onKeyEvent((event) => {
+  if (event.key === 'Enter') {
+    // 处理回车键
+    submitSelection()
+  } else if (event.key === 'ArrowDown') {
+    // 向下导航
+    selectNext()
+  } else if (event.key === 'ArrowUp') {
+    // 向上导航
+    selectPrev()
+  } else if (event.metaKey && event.key === 'k') {
+    // 处理 Cmd+K
+    openSearch()
+  }
+})
+```
+
+### 3. 键盘事件自动处理
+
+当插件的 UI View 附加到 CoreBox 时，系统会自动处理以下行为：
+
+#### ESC 键自动退出
+- 在 UI View 中按下 ESC 键会**自动退出 UI 模式**（deactivate providers）
+- 插件无需手动处理 ESC 键的退出逻辑
+- 这与 CoreBox 主界面的 ESC 行为保持一致
+
+#### 键盘事件转发
+以下按键会从 CoreBox 主输入框转发到插件 UI View：
+- **Enter** - 确认/提交
+- **ArrowUp / ArrowDown** - 上下导航
+- **Meta/Ctrl + 任意键** - 快捷键组合（Cmd+V 除外，用于粘贴）
+
+> **注意**：`ArrowLeft` 和 `ArrowRight` 不会被转发，因为它们用于输入框中的文本编辑。如果需要左右导航，请使用 `Meta/Ctrl + ArrowLeft/ArrowRight`。
+
+```typescript
+// 键盘事件数据结构
+interface ForwardedKeyEvent {
+  key: string       // 按键名称，如 'Enter', 'ArrowDown'
+  code: string      // 按键代码，如 'Enter', 'ArrowDown'
+  metaKey: boolean  // Cmd/Win 键是否按下
+  ctrlKey: boolean  // Ctrl 键是否按下
+  altKey: boolean   // Alt 键是否按下
+  shiftKey: boolean // Shift 键是否按下
+  repeat: boolean   // 是否为重复按键
+}
 ```
 
 ## 废弃的 API
@@ -151,7 +198,7 @@ onInit(context) {
 export default {
   onInit(context) {
     const { feature, box } = context.utils
-    
+
     // 监听输入变化
     feature.onInputChange((input) => {
       if (input.length > 2) {
@@ -163,10 +210,10 @@ export default {
       }
     })
   },
-  
+
   onFeatureTriggered(featureId, query, feature) {
     const { feature: featureSDK, box } = this.context.utils
-    
+
     // 推送结果
     featureSDK.pushItems([
       {
@@ -176,10 +223,10 @@ export default {
         source: { id: this.pluginName, name: this.pluginName }
       }
     ])
-    
+
     // 扩展窗口显示结果
     box.expand({ length: 5 })
-    
+
     // 3秒后隐藏
     setTimeout(() => {
       box.hide()
@@ -207,7 +254,8 @@ export default {
 - `core-box:get-input` - 获取当前输入值
 - `core-box:set-input` - 设置输入框内容
 - `core-box:clear-input` - 清空输入框
-- `core-box:input-changed` - 输入变化广播（主进程 → 插件）
+- `core-box:input-change` - 输入变化广播（主进程 → 插件）
+- `core-box:key-event` - 键盘事件转发（主进程 → 插件 UI View）
 - `core-box:set-input-visibility` - 设置输入框可见性（主进程 → 渲染进程）
 - `core-box:request-input-value` - 请求输入值（主进程 → 渲染进程）