@talex-touch/utils 1.0.31 → 1.0.33

package/types/update.ts

@@ -1,11 +1,15 @@
-// 更新源类型枚举
+/**
+ * Known update provider types.
+ */
 export enum UpdateProviderType {
   GITHUB = 'github',
   OFFICIAL = 'official',
-  CUSTOM = 'custom'
+  CUSTOM = 'custom',
 }
 
-// 更新源配置接口
+/**
+ * Describes the remote endpoint that serves release metadata.
+ */
 export interface UpdateSourceConfig {
   type: UpdateProviderType
   name: string
@@ -14,7 +18,9 @@ export interface UpdateSourceConfig {
   priority: number
 }
 
-// 下载资源接口
+/**
+ * Represents a downloadable build artifact.
+ */
 export interface DownloadAsset {
   name: string
   url: string
@@ -24,7 +30,9 @@ export interface DownloadAsset {
   checksum?: string
 }
 
-// GitHub Release接口（兼容GitHub API格式）
+/**
+ * Minimal subset of the GitHub release payload that the updater consumes.
+ */
 export interface GitHubRelease {
   tag_name: string
   name: string
@@ -33,7 +41,9 @@ export interface GitHubRelease {
   assets: DownloadAsset[]
 }
 
-// 更新检查结果接口
+/**
+ * Standardized shape of an update check response.
+ */
 export interface UpdateCheckResult {
   hasUpdate: boolean
   release?: GitHubRelease
@@ -41,7 +51,21 @@ export interface UpdateCheckResult {
   source: string
 }
 
-// 自定义更新源配置
+export type UpdateUserAction = 'update-now' | 'skip' | 'remind-later'
+
+export interface CachedUpdateRecord {
+  release: GitHubRelease
+  channel: AppPreviewChannel
+  status: 'pending' | 'skipped' | 'snoozed' | 'acknowledged'
+  fetchedAt: number
+  snoozeUntil?: number | null
+  tag: string
+  source: string
+}
+
+/**
+ * Custom provider definition used to extend the updater beyond the built-ins.
+ */
 export interface CustomUpdateConfig {
   name: string
   url: string
@@ -49,49 +73,95 @@ export interface CustomUpdateConfig {
   headers?: Record<string, string>
 }
 
-// 应用预览渠道枚举
+/**
+ * Build channels supported by the desktop client.
+ */
 export enum AppPreviewChannel {
-  MASTER = 'master',
-  SNAPSHOT = 'snapshot'
+  RELEASE = 'RELEASE',
+  BETA = 'BETA',
+  SNAPSHOT = 'SNAPSHOT',
 }
 
-// 更新设置配置
+/**
+ * Scheduler presets used by the polling worker.
+ */
+export type UpdateFrequency = 'everyday' | '1day' | '3day' | '7day' | '1month' | 'never'
+
+/**
+ * User and system configurable update preferences.
+ */
 export interface UpdateSettings {
   enabled: boolean
-  frequency: 'startup' | 'daily' | 'weekly' | 'manual'
+  frequency: UpdateFrequency
   source: UpdateSourceConfig
-  crossChannel: boolean
+  updateChannel: AppPreviewChannel
   ignoredVersions: string[]
   customSources: CustomUpdateConfig[]
+  /**
+   * Timestamp (ms) of the last successful update check.
+   */
+  lastCheckedAt?: number | null
+  /**
+   * Enable/disable local caching of remote responses.
+   */
+  cacheEnabled?: boolean
+  /**
+   * Cache TTL in minutes.
+   */
+  cacheTTL?: number
+  /**
+   * Enable retry logic for transient failures.
+   */
+  rateLimitEnabled?: boolean
+  /**
+   * Maximum retry attempts when the provider throttles requests.
+   */
+  maxRetries?: number
+  /**
+   * Base retry delay in milliseconds.
+   */
+  retryDelay?: number
 }
 
-// 默认更新设置
+/**
+ * Safe defaults used when no user configuration exists yet.
+ */
 export const defaultUpdateSettings: UpdateSettings = {
   enabled: true,
-  frequency: 'startup',
+  frequency: 'everyday',
   source: {
     type: UpdateProviderType.GITHUB,
     name: 'GitHub Releases',
     url: 'https://api.github.com/repos/talex-touch/tuff/releases',
     enabled: true,
-    priority: 1
+    priority: 1,
   },
-  crossChannel: false,
+  updateChannel: AppPreviewChannel.RELEASE,
   ignoredVersions: [],
-  customSources: []
+  customSources: [],
+  lastCheckedAt: null,
+  cacheEnabled: true,
+  cacheTTL: 30,
+  rateLimitEnabled: true,
+  maxRetries: 3,
+  retryDelay: 2000,
 }
 
-// 更新错误类型
+/**
+ * Categorized error types emitted by the updater pipeline.
+ */
 export enum UpdateErrorType {
   NETWORK_ERROR = 'network_error',
   TIMEOUT_ERROR = 'timeout_error',
   API_ERROR = 'api_error',
   PARSE_ERROR = 'parse_error',
   VERSION_ERROR = 'version_error',
-  UNKNOWN_ERROR = 'unknown_error'
+  UNKNOWN_ERROR = 'unknown_error',
 }
 
-// 更新错误接口
+/**
+ * Error type used across providers.
+ */
 export interface UpdateError extends Error {
   type: UpdateErrorType
   code?: string

package/core-box/README.md

@@ -1,218 +0,0 @@
-# Core Box Package
-
-The Core Box package provides unified type definitions and utility functions for the TUFF search box system. This package contains the foundational types and tools used across the entire project for search result management and plugin integration.
-
-## Features
-
-### 🎯 Unified Type System
-- **ISearchItem**: Universal search result item interface
-- **IRenderConfig**: Flexible rendering configuration with multiple modes
-- **IDataItem**: Extended interface for data processing results
-- **IAppItem**: Specialized interface for application results
-- **IFileItem**: Specialized interface for file results
-- **IFeatureItem**: Specialized interface for plugin feature results
-
-### 🎨 Render Modes
-The package supports multiple rendering modes for search results:
-
-- **STANDARD**: Default text-based rendering
-- **URL**: URL rendering - loads and displays remote URL content
-- **HTML**: Rich HTML content rendering
-- **JAVASCRIPT**: JavaScript code with syntax highlighting
-- **JSX**: React JSX component rendering
-- **VUE_SFC**: Vue Single File Component rendering
-
-### 🛠️ Utility Functions
-Comprehensive set of utility functions for creating and managing search results:
-
-- `SearchUtils.createSearchItem()`: Create basic search items
-- `SearchUtils.createDataItem()`: Create data processing results
-- `SearchUtils.createAppItem()`: Create application results
-- `SearchUtils.createFileItem()`: Create file results
-- `SearchUtils.createFeatureItem()`: Create plugin feature results
-- `SearchUtils.createErrorItem()`: Create error state items
-- `SearchUtils.sortByPriority()`: Sort results by relevance
-- `SearchUtils.removeDuplicates()`: Remove duplicate results
-- `SearchUtils.filterByConfidence()`: Filter by confidence score
-- `SearchUtils.groupByPluginType()`: Group results by type
-
-## Usage Examples
-
-### Basic Search Item
-```typescript
-import { SearchUtils, RenderMode } from '@talex-touch/utils';
-
-const basicItem = SearchUtils.createSearchItem({
-  name: "My Feature",
-  desc: "A useful plugin feature",
-  pluginName: "my-plugin",
-  keyWords: ["feature", "utility"],
-  render: {
-    mode: RenderMode.STANDARD
-  }
-});
-```
-
-### Data Processing Result
-```typescript
-const dataItem = SearchUtils.createDataItem({
-  name: "Translation Result",
-  desc: "English to Chinese translation",
-  pluginName: "translator",
-  source: "google-translate",
-  dataType: "translation",
-  originalData: "Hello World",
-  processedData: "你好世界",
-  confidence: 95,
-  duration: 120,
-  render: {
-    mode: RenderMode.STANDARD
-  }
-});
-```
-
-### HTML Rendering
-```typescript
-const htmlItem = SearchUtils.createSearchItem({
-  name: "Rich Content",
-  desc: "HTML formatted result",
-  pluginName: "content-plugin",
-  render: {
-    mode: RenderMode.HTML,
-    content: "<div><h3>Title</h3><p>Content</p></div>",
-    options: {
-      trusted: true,
-      className: "custom-content"
-    }
-  }
-});
-```
-
-### Code Rendering
-```typescript
-const codeItem = SearchUtils.createDataItem({
-  name: "JavaScript Function",
-  desc: "Generated code snippet",
-  pluginName: "code-generator",
-  dataType: "javascript",
-  processedData: "function hello() { return 'world'; }",
-  render: {
-    mode: RenderMode.JAVASCRIPT,
-    content: "function hello() { return 'world'; }",
-    options: {
-      syntaxHighlight: true,
-      showLineNumbers: true,
-      theme: "dark"
-    }
-  }
-});
-```
-
-### URL Rendering with Preview
-```typescript
-const urlItem = SearchUtils.createSearchItem({
-  name: "GitHub Repository",
-  desc: "TUFF project",
-  pluginName: "web-search",
-  render: {
-    mode: RenderMode.URL,
-    content: "https://github.com/talex-touch/talex-touch", // The actual URL to load
-    preview: {
-      enabled: true,
-      title: "Tuff",                                // Preview metadata
-      description: "Modern desktop application framework", // Preview description
-      image: "https://github.com/talex-touch.png"         // Preview image
-    }
-  }
-});
-```
-
-**Note**:
-- `content`: The remote URL that will be loaded and displayed
-- `preview`: Metadata shown before/alongside the loaded URL content
-
-## Type Definitions
-
-### ISearchItem
-The core interface for all search results:
-
-```typescript
-interface ISearchItem {
-  name: string;                    // Display name
-  desc: string;                    // Description
-  icon: ITuffIcon;              // Icon configuration
-  push: boolean;                   // Push mode support
-  names: string[];                 // Searchable names
-  keyWords: string[];             // Search keywords
-  pluginType: string;             // Plugin type
-  type: string;                   // General type
-  value: string;                  // Associated value
-  render?: IRenderConfig;         // Render configuration
-  // ... additional properties
-}
-```
-
-### IRenderConfig
-Configuration for custom rendering:
-
-```typescript
-interface IRenderConfig {
-  mode: RenderMode;               // Rendering mode
-  content?: string;               // Content to render
-  options?: {                     // Render options
-    syntaxHighlight?: boolean;
-    theme?: string;
-    showLineNumbers?: boolean;
-    className?: string;
-    style?: Record<string, string>;
-    trusted?: boolean;
-  };
-  preview?: {                     // URL preview config
-    enabled?: boolean;
-    image?: string;
-    title?: string;
-    description?: string;
-  };
-}
-```
-
-## Integration
-
-This package is automatically exported from `@talex-touch/utils`:
-
-```typescript
-import {
-  ISearchItem,
-  IDataItem,
-  SearchUtils,
-  RenderMode
-} from '@talex-touch/utils';
-```
-
-## Best Practices
-
-1. **Always specify render mode**: Even for standard rendering, explicitly set the render mode
-2. **Use appropriate specialized interfaces**: Use IDataItem for data processing, IAppItem for applications, etc.
-3. **Include confidence scores**: For data processing results, always include confidence levels
-4. **Sanitize HTML content**: When using HTML render mode, ensure content is safe
-5. **Provide meaningful keywords**: Include relevant search terms in the keyWords array
-6. **Use consistent naming**: Follow established naming conventions for plugin types
-
-## Migration Guide
-
-If you're migrating from the old type system:
-
-1. Replace `ITranslationItem` with `IDataItem`
-2. Update render configurations to use the new `IRenderConfig` interface
-3. Use `SearchUtils` functions instead of manual object creation
-4. Update import paths to use `@talex-touch/utils`
-
-## Contributing
-
-When adding new types or utilities:
-
-1. Add comprehensive TSDoc comments in English
-2. Include usage examples in documentation
-3. Follow the established naming conventions
-4. Add appropriate unit tests
-5. Update this README with new features

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

@@ -1,258 +0,0 @@
-/**
- * TUFF Builder 示例文件
- * 展示如何使用 TuffBuilder 工具类创建和管理 TuffItem 对象
- */
-
-import { TuffItemBuilder, TuffFactory, TuffListBuilder, TuffUtils } from './tuff-builder';
-import type { TuffItem } from '../tuff/tuff-dsl';
-
-// ==================== 基本用法示例 ====================
-
-/**
- * 示例 1: 使用 TuffItemBuilder 创建单个项目
- */
-function createSingleItem(): TuffItem {
-  // 使用 Builder 模式创建一个完整的 TuffItem
-  const item = new TuffItemBuilder('doc-1')
-    .setSource('plugin', 'file-explorer')
-    .setTitle('文档.docx')
-    .setDescription('Word 文档')
-    .setIcon(TuffUtils.createIcon('📄'))
-    .setKind('file')
-    .addTag(TuffUtils.createTag('文档', '#4285F4'))
-    .addTag(TuffUtils.createTag('最近', '#34A853'))
-    .setAccessory('2023-06-15')
-    .addAction(TuffUtils.createAction('open', 'open', '打开', true))
-    .addAction(TuffUtils.createAction('copy', 'copy', '复制路径', false))
-    .setMeta({
-      file: {
-        path: '/Users/documents/文档.docx',
-        size: 1024 * 1024 * 2, // 2MB
-        modified_at: '2023-06-15T10:30:00Z'
-      }
-    })
-    .build();
-
-  return item;
-}
-
-/**
- * 示例 2: 使用 TuffFactory 快速创建常见类型的项目
- */
-function createCommonItems(): TuffItem[] {
-  const items: TuffItem[] = [];
-
-  // 创建基本项目
-  const basicItem = TuffFactory.createBasicItem(
-    '基本项目',
-    'system',
-    'basic-example',
-    'text'
-  );
-  items.push(basicItem);
-
-  // 创建文件项目
-  const fileItem = TuffFactory.createFileItem(
-    'config.json',
-    '/Users/config.json',
-    'plugin',
-    'settings-manager'
-  );
-  items.push(fileItem);
-
-  // 创建文件夹项目
-  const folderItem = TuffFactory.createFolderItem(
-    '项目文件夹',
-    '/Users/projects',
-    'plugin',
-    'file-explorer'
-  );
-  items.push(folderItem);
-
-  // 创建链接项目
-  const urlItem = TuffFactory.createUrlItem(
-    'Tuff 文档',
-    'https://example.com/tuff-docs',
-    'plugin',
-    'web-search'
-  );
-  items.push(urlItem);
-
-  // 创建应用项目
-  const appItem = TuffFactory.createAppItem(
-    'Visual Studio Code',
-    '/Applications/Visual Studio Code.app',
-    'com.microsoft.VSCode',
-    'plugin',
-    'app-launcher'
-  );
-  items.push(appItem);
-
-  // 创建命令项目
-  const commandItem = TuffFactory.createCommandItem(
-    '查看系统信息',
-    'system_profiler SPHardwareDataType',
-    'plugin',
-    'terminal'
-  );
-  items.push(commandItem);
-
-  return items;
-}
-
-/**
- * 示例 3: 使用 TuffBatchBuilder 批量创建项目
- */
-function createBatchItems(): TuffItem[] {
-  // 创建批量构建器，设置共享的来源信息
-  const batchBuilder = new TuffListBuilder('plugin', 'file-explorer')
-    .setSharedKind('file')
-    
-    .addSharedAction(TuffUtils.createAction('open', 'open', '打开', true));
-
-  // 添加多个项目
-  batchBuilder
-    .addItem(builder => {
-      builder
-        .setTitle('文档1.docx')
-        .setIcon(TuffUtils.createIcon('📄'))
-        .setDescription('Word 文档')
-        .addTag(TuffUtils.createTag('文档', '#4285F4'));
-    })
-    .addItem(builder => {
-      builder
-        .setTitle('图片.jpg')
-        .setIcon(TuffUtils.createIcon('🖼️'))
-        .setDescription('JPG 图片')
-        .addTag(TuffUtils.createTag('图片', '#FBBC05'));
-    })
-    .addItem(builder => {
-      builder
-        .setTitle('表格.xlsx')
-        .setIcon(TuffUtils.createIcon('📊'))
-        .setDescription('Excel 表格')
-        .addTag(TuffUtils.createTag('表格', '#34A853'));
-    });
-
-  // 批量添加简单项目
-  batchBuilder.addItemsFromData([
-    { name: '笔记1.txt' },
-    { name: '笔记2.txt' },
-    { name: '笔记3.txt' }
-  ], (builder, item) => builder.setTitle(item.name));
-
-  // 从数据对象批量创建项目
-  const fileData = [
-    { name: '报告.pdf', type: 'pdf', size: 1024 * 1024 * 3, modified: '2023-06-10' },
-    { name: '演示.pptx', type: 'pptx', size: 1024 * 1024 * 5, modified: '2023-06-12' },
-    { name: '数据.csv', type: 'csv', size: 1024 * 512, modified: '2023-06-14' }
-  ];
-
-  batchBuilder.addItemsFromData(fileData, (builder, file) => {
-    let icon = '📄';
-    if (file.type === 'pdf') icon = '📕';
-    if (file.type === 'pptx') icon = '📊';
-    if (file.type === 'csv') icon = '📈';
-
-    builder
-      .setTitle(file.name)
-      .setIcon(TuffUtils.createIcon(icon))
-      .setDescription(`${file.type.toUpperCase()} 文件`)
-      .setAccessory(file.modified)
-      .setMeta({
-        file: {
-          path: file.name,
-          size: file.size,
-          modified_at: file.modified
-        }
-      });
-  });
-
-  return batchBuilder.build();
-}
-
-/**
- * 示例 4: 使用 TuffUtils 处理项目列表
- */
-function processItems(items: TuffItem[]): void {
-  // 过滤文件类型的项目
-  const fileItems = TuffUtils.filterByKind(items, 'file');
-  console.log(`文件项目数量: ${fileItems.length}`);
-
-  // 按标题搜索项目
-  const searchResults = TuffUtils.searchByTitle(items, '文档');
-  console.log(`包含"文档"的项目数量: ${searchResults.length}`);
-
-  // 按评分排序项目
-  const sortedByScore = TuffUtils.sortByScore(items);
-  console.log('按评分排序的前 3 个项目:');
-  sortedByScore.slice(0, 3).forEach(item => {
-    console.log(` - ${item.render.basic?.title} (评分: ${item.scoring?.final ?? 0})`);
-  });
-
-  // 按标题排序项目
-  const sortedByTitle = TuffUtils.sortByTitle(items);
-  console.log('按标题排序的前 3 个项目:');
-  sortedByTitle.slice(0, 3).forEach(item => {
-    console.log(` - ${item.render.basic?.title}`);
-  });
-}
-
-/**
- * 示例 5: 从普通对象创建 TuffItem
- */
-function createFromObjects(): TuffItem[] {
-  // 示例数据
-  const data = [
-    { name: '项目 A', description: '这是项目 A 的描述', type: 'project' },
-    { name: '任务 B', description: '这是任务 B 的描述', type: 'task', priority: 'high' },
-    { name: '笔记 C', description: '这是笔记 C 的内容', type: 'note', tags: ['重要', '工作'] }
-  ];
-
-  // 从对象数组创建 TuffItem 数组
-  return TuffUtils.fromObjects(data, 'plugin', 'data-converter');
-}
-
-/**
- * 运行所有示例
- */
-function runAllExamples(): void {
-  console.log('===== 示例 1: 使用 TuffItemBuilder 创建单个项目 =====');
-  const singleItem = createSingleItem();
-  console.log(JSON.stringify(singleItem, null, 2));
-
-  console.log('\n===== 示例 2: 使用 TuffFactory 快速创建常见类型的项目 =====');
-  const commonItems = createCommonItems();
-  console.log(`创建了 ${commonItems.length} 个项目`);
-
-  console.log('\n===== 示例 3: 使用 TuffBatchBuilder 批量创建项目 =====');
-  const batchItems = createBatchItems();
-  console.log(`批量创建了 ${batchItems.length} 个项目`);
-
-  console.log('\n===== 示例 4: 使用 TuffUtils 处理项目列表 =====');
-  // 合并所有创建的项目
-  const allItems = [singleItem, ...commonItems, ...batchItems];
-  processItems(allItems);
-
-  console.log('\n===== 示例 5: 从普通对象创建 TuffItem =====');
-  const objectItems = createFromObjects();
-  console.log(`从对象创建了 ${objectItems.length} 个项目`);
-  objectItems.forEach(item => {
-    console.log(` - ${item.render.basic?.title}`);
-  });
-}
-
-// 如果直接运行此文件，则执行所有示例
-if (require.main === module) {
-  runAllExamples();
-}
-
-// 导出示例函数，以便其他模块可以使用
-export {
-  createSingleItem,
-  createCommonItems,
-  createBatchItems,
-  processItems,
-  createFromObjects,
-  runAllExamples
-};

package/core-box/run-tests.sh

@@ -1,7 +0,0 @@
-#!/bin/bash
-
-# 运行 TUFF Builder 测试
-# 测试文件位于 packages/test/src/core-box 目录下
-cd "$(dirname "$0")"
-cd ../../../
-pnpm --filter test test

package/core-box/search.ts

@@ -1 +0,0 @@
-export {}