@talex-touch/utils 1.0.42 → 1.0.44

package/plugin/sdk-version.ts

@@ -0,0 +1,231 @@
+import type { SdkApiVersion } from './index'
+
+/**
+ * Known SDK API versions (format: YYMMDD).
+ *
+ * Ranges (rough):
+ * - < 251212: legacy mode (no permission enforcement, no category requirement)
+ * - 251212 ~ 260113: permission enforcement + new input model baseline
+ * - >= 260114: `manifest.json.category` is required for plugin grouping
+ * - >= 260121: `tfileScope` is required when requesting tfile access
+ * - >= 260215: plugin sqlite sdk is available
+ */
+export enum SdkApi {
+  /**
+   * 2025-12-12: permissions + input model baseline.
+   */
+  V251212 = 251212,
+  /**
+   * 2026-01-14: require `manifest.json.category` for plugins.
+   */
+  V260114 = 260114,
+  /**
+   * 2026-01-21: add tfile permission + scope enforcement.
+   */
+  V260121 = 260121,
+  /**
+   * 2026-02-15: add plugin sqlite sdk support.
+   */
+  V260215 = 260215,
+}
+
+/**
+ * Supported SDK versions in descending order.
+ * Used to gracefully fallback for unknown/invalid sdkapi values.
+ */
+export const SUPPORTED_SDK_VERSIONS: readonly SdkApiVersion[] = [
+  SdkApi.V260215,
+  SdkApi.V260121,
+  SdkApi.V260114,
+  SdkApi.V251212,
+]
+
+/**
+ * Current SDK API version.
+ * Updated when breaking changes are introduced to plugin APIs.
+ */
+export const CURRENT_SDK_VERSION: SdkApiVersion = SdkApi.V260215
+
+/**
+ * Minimum SDK version required for permission enforcement.
+ * Plugins below this version will bypass permission checks with a warning.
+ */
+export const PERMISSION_ENFORCEMENT_MIN_VERSION: SdkApiVersion = SdkApi.V251212
+
+/**
+ * Minimum SDK version required for `manifest.json.category`.
+ */
+export const CATEGORY_REQUIRED_MIN_VERSION: SdkApiVersion = SdkApi.V260114
+
+/**
+ * Minimum SDK version required for `tfileScope` enforcement.
+ */
+export const TFILE_SCOPE_REQUIRED_MIN_VERSION: SdkApiVersion = SdkApi.V260121
+
+/**
+ * SDK version compatibility result
+ */
+export interface SdkCompatibilityResult {
+  /** Whether the plugin SDK version is compatible */
+  compatible: boolean
+  /** Whether permission enforcement should be applied */
+  enforcePermissions: boolean
+  /** Warning message if compatibility issues exist */
+  warning?: string
+  /** Suggestion for fixing compatibility issues */
+  suggestion?: string
+}
+
+/**
+ * Check SDK version compatibility for a plugin.
+ * @param pluginSdkVersion - The sdkapi value from plugin manifest (undefined if not declared)
+ * @param pluginName - Plugin name for error messages
+ * @returns Compatibility check result
+ */
+export function checkSdkCompatibility(
+  pluginSdkVersion: SdkApiVersion | undefined,
+  pluginName: string,
+): SdkCompatibilityResult {
+  // No sdkapi declared - legacy plugin
+  if (pluginSdkVersion === undefined) {
+    return {
+      compatible: true,
+      enforcePermissions: false,
+      warning: `Plugin "${pluginName}" does not declare sdkapi version. Permission enforcement is disabled for compatibility.`,
+      suggestion: `Add "sdkapi": ${CURRENT_SDK_VERSION} to manifest.json to enable permission enforcement.`,
+    }
+  }
+
+  const resolved = resolveSdkApiVersion(pluginSdkVersion)
+  const warningParts: string[] = []
+  const suggestionParts: string[] = []
+
+  // Validate + normalize to a supported SDK version (graceful fallback)
+  if (resolved === undefined) {
+    return {
+      compatible: true,
+      enforcePermissions: false,
+      warning: `Plugin "${pluginName}" has invalid sdkapi value: ${pluginSdkVersion}. Falling back to legacy mode.`,
+      suggestion: `Use format YYMMDD (e.g., "sdkapi": ${CURRENT_SDK_VERSION}).`,
+    }
+  }
+
+  if (resolved !== pluginSdkVersion) {
+    warningParts.push(
+      `Plugin "${pluginName}" declares sdkapi ${pluginSdkVersion}, but it is not a supported SDK marker. Falling back to ${resolved}.`,
+    )
+    suggestionParts.push(`Use a supported sdkapi marker, e.g., ${CURRENT_SDK_VERSION}.`)
+  }
+
+  // Version too old - bypass permissions with warning
+  if (resolved < PERMISSION_ENFORCEMENT_MIN_VERSION) {
+    return {
+      compatible: true,
+      enforcePermissions: false,
+      warning: [
+        ...warningParts,
+        `Plugin "${pluginName}" uses legacy SDK version ${resolved}. Permission enforcement is disabled.`,
+      ].join(' '),
+      suggestion: [
+        ...suggestionParts,
+        `Update to sdkapi: ${CURRENT_SDK_VERSION} for full permission support.`,
+      ].join(' '),
+    }
+  }
+
+  // Version newer than current - might use unsupported features
+  if (pluginSdkVersion > CURRENT_SDK_VERSION) {
+    return {
+      compatible: true,
+      enforcePermissions: true,
+      warning: [
+        ...warningParts,
+        `Plugin "${pluginName}" requires SDK version ${pluginSdkVersion}, but current version is ${CURRENT_SDK_VERSION}. Some features may not work.`,
+      ].join(' '),
+      suggestion: [
+        ...suggestionParts,
+        `Update Tuff to the latest version for full compatibility.`,
+      ].join(' '),
+    }
+  }
+
+  // Perfect match or compatible older version
+  return {
+    compatible: true,
+    enforcePermissions: true,
+    warning: warningParts.length ? warningParts.join(' ') : undefined,
+    suggestion: suggestionParts.length ? suggestionParts.join(' ') : undefined,
+  }
+}
+
+/**
+ * Resolve a plugin-declared sdkapi to the nearest supported SDK marker.
+ *
+ * Rules:
+ * - Invalid values => undefined (legacy)
+ * - Unknown future versions => fallback to the latest supported <= declared
+ * - Known versions => keep as-is
+ */
+export function resolveSdkApiVersion(raw: unknown): SdkApiVersion | undefined {
+  const num
+    = typeof raw === 'number'
+      ? raw
+      : typeof raw === 'string'
+        ? parseSdkVersion(raw)
+        : undefined
+
+  if (num === undefined || !isValidSdkVersion(num)) {
+    return undefined
+  }
+
+  for (const v of SUPPORTED_SDK_VERSIONS) {
+    if (num >= v) {
+      return v
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Validate SDK version format (YYMMDD)
+ */
+export function isValidSdkVersion(version: number): boolean {
+  if (!Number.isInteger(version) || version < 100000 || version > 999999) {
+    return false
+  }
+
+  const str = version.toString()
+  const year = Number.parseInt(str.substring(0, 2), 10)
+  const month = Number.parseInt(str.substring(2, 4), 10)
+  const day = Number.parseInt(str.substring(4, 6), 10)
+
+  // Basic validation: year 20-99, month 01-12, day 01-31
+  return year >= 20 && year <= 99 && month >= 1 && month <= 12 && day >= 1 && day <= 31
+}
+
+/**
+ * Format SDK version for display
+ * @param version - SDK version number (YYMMDD)
+ * @returns Formatted string like "25.12.12"
+ */
+export function formatSdkVersion(version: SdkApiVersion): string {
+  const str = version.toString().padStart(6, '0')
+  return `${str.substring(0, 2)}.${str.substring(2, 4)}.${str.substring(4, 6)}`
+}
+
+/**
+ * Parse SDK version from string
+ * @param str - Version string like "251212" or "25.12.12"
+ * @returns SDK version number or undefined if invalid
+ */
+export function parseSdkVersion(str: string): SdkApiVersion | undefined {
+  // Remove dots if present
+  const cleaned = str.replace(/\./g, '')
+  const num = Number.parseInt(cleaned, 10)
+
+  if (isValidSdkVersion(num)) {
+    return num
+  }
+  return undefined
+}

package/preload/renderer.ts

@@ -1,7 +1,8 @@
 import type { LoadingEvent, LoadingMode, LoadingState, PreloadAPI } from './loading'
+import { hasWindow } from '../env'
 
 function getPreloadApi(): PreloadAPI | null {
-  if (typeof window === 'undefined')
+  if (!hasWindow())
     return null
   return (window as any).api ?? null
 }
@@ -37,7 +38,7 @@ export function preloadDebugStep(message: string, delta = 0.08): void {
 }
 
 export function preloadRemoveOverlay(): void {
-  if (typeof window === 'undefined')
+  if (!hasWindow())
     return
   window.postMessage({ payload: 'removeLoading' }, '*')
 }

package/renderer/hooks/arg-mapper.ts

@@ -7,6 +7,8 @@ export interface IArgMapperOptions {
   touchType?: 'main' | 'core-box'
   /** The sub-type for core-box windows (e.g., division-box) */
   coreType?: 'division-box'
+  /** Whether this is a meta-overlay WebContentsView */
+  metaOverlay?: 'true' | 'false'
   /** User data directory path */
   userDataDir?: string
   /** Application path */
@@ -33,14 +35,17 @@ declare global {
  * @param args - Array of command line arguments (defaults to process.argv)
  * @returns Mapped command line arguments as key-value pairs
  */
-export function useArgMapper(args: string[] = process.argv): IArgMapperOptions {
-  if (window.$argMapper) return window.$argMapper
+export function useArgMapper(args: string[] = (globalThis as any)?.process?.argv ?? []): IArgMapperOptions {
+  if (window.$argMapper)
+    return window.$argMapper
 
   const mapper: IArgMapperOptions = {}
   for (const arg of args) {
     if (arg.startsWith('--') && arg.includes('=')) {
       const [key, ...valueParts] = arg.slice(2).split('=')
       const value = valueParts.join('=')
+      if (!key)
+        continue
       const camelCaseKey = key.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())
       mapper[camelCaseKey] = value
     }
@@ -90,3 +95,12 @@ export function useCoreType() {
 export function isDivisionBox() {
   return isCoreBox() && useCoreType() === 'division-box'
 }
+
+/**
+ * Checks if the current window is a meta-overlay WebContentsView
+ * @returns True if the current window is a meta-overlay
+ */
+export function isMetaOverlay() {
+  const argMapper = useArgMapper()
+  return argMapper.metaOverlay === 'true'
+}

package/renderer/hooks/index.ts

@@ -1,5 +1,18 @@
 export * from './arg-mapper'
 export * from './initialize'
 export * from './performance'
+export * from './use-agent-market-sdk'
+export * from './use-agents-sdk'
+export * from './use-app-sdk'
 export * from './use-channel'
+export * from './use-download-sdk'
 export * from './use-intelligence'
+export * from './use-intelligence-sdk'
+export * from './use-intelligence-stats'
+export * from './use-market-sdk'
+export * from './use-notification-sdk'
+export * from './use-permission-sdk'
+export * from './use-platform-sdk'
+export * from './use-plugin-sdk'
+export * from './use-settings-sdk'
+export * from './use-update-sdk'

package/renderer/hooks/initialize.ts

@@ -102,12 +102,13 @@ export function useInitialize(): IInitializationInfo {
   }
 
   const now = Date.now()
+  const runtimePlatform = (globalThis as any)?.process?.platform ?? navigator.platform
   const initInfo: IInitializationInfo = {
     initTimestamp: now,
     initTime: new Date(now).toISOString(),
     userAgent: navigator.userAgent,
     currentUrl: window.location.href,
-    platform: process.platform,
+    platform: runtimePlatform,
     screenResolution: {
       width: screen.width,
       height: screen.height,

package/renderer/hooks/use-agent-market-sdk.ts

@@ -0,0 +1,7 @@
+import { useTuffTransport } from '../../transport'
+import { createAgentMarketSdk } from '../../transport/sdk/domains/agents-market'
+
+export function useAgentMarketSdk() {
+  const transport = useTuffTransport()
+  return createAgentMarketSdk(transport)
+}

package/renderer/hooks/use-agent-market.ts

@@ -0,0 +1,106 @@
+import type { Ref } from 'vue'
+import type {
+  AgentCategory,
+  AgentInstallResult,
+  AgentSearchOptions,
+  AgentSearchResult,
+  MarketAgentInfo,
+} from '../../transport/sdk/domains/agents-market'
+import { ref } from 'vue'
+import { useAgentMarketSdk } from './use-agent-market-sdk'
+
+export type {
+  AgentCategory,
+  AgentInstallResult,
+  AgentSearchOptions,
+  AgentSearchResult,
+  MarketAgentInfo,
+}
+
+interface AgentMarketComposable {
+  // Search and browse
+  searchAgents: (options?: AgentSearchOptions) => Promise<AgentSearchResult>
+  getAgentDetails: (agentId: string) => Promise<MarketAgentInfo | null>
+  getFeaturedAgents: () => Promise<MarketAgentInfo[]>
+  getInstalledAgents: () => Promise<MarketAgentInfo[]>
+  getCategories: () => Promise<AgentCategory[]>
+
+  // Install/Uninstall
+  installAgent: (agentId: string, version?: string) => Promise<AgentInstallResult>
+  uninstallAgent: (agentId: string) => Promise<AgentInstallResult>
+  checkUpdates: () => Promise<MarketAgentInfo[]>
+
+  // State
+  isLoading: Ref<boolean>
+  lastError: Ref<string | null>
+}
+
+/**
+ * Agent Market Composable
+ *
+ * Provides access to the agent marketplace for browsing, searching,
+ * and installing agents.
+ *
+ * @example
+ * ```ts
+ * const { searchAgents, installAgent, isLoading } = useAgentMarket()
+ *
+ * // Search agents
+ * const result = await searchAgents({ keyword: 'file', category: 'productivity' })
+ *
+ * // Install an agent
+ * const installResult = await installAgent('community.workflow-agent')
+ * ```
+ */
+/**
+ * @deprecated 请优先使用 useAgentMarketSdk() 直接调用 typed domain SDK，该 hook 仅保留兼容壳。
+ */
+export function useAgentMarket(): AgentMarketComposable {
+  const isLoading = ref(false)
+  const lastError = ref<string | null>(null)
+  const agentMarketSdk = useAgentMarketSdk()
+
+  async function withLoading<T>(fn: () => Promise<T>): Promise<T> {
+    isLoading.value = true
+    lastError.value = null
+    try {
+      return await fn()
+    }
+    catch (error) {
+      lastError.value = error instanceof Error ? error.message : String(error)
+      throw error
+    }
+    finally {
+      isLoading.value = false
+    }
+  }
+
+  return {
+    searchAgents: (options?: AgentSearchOptions) =>
+      withLoading(() => agentMarketSdk.searchAgents(options)),
+
+    getAgentDetails: (agentId: string) =>
+      withLoading(() => agentMarketSdk.getAgentDetails(agentId)),
+
+    getFeaturedAgents: () =>
+      withLoading(() => agentMarketSdk.getFeaturedAgents()),
+
+    getInstalledAgents: () =>
+      withLoading(() => agentMarketSdk.getInstalledAgents()),
+
+    getCategories: () =>
+      withLoading(() => agentMarketSdk.getCategories()),
+
+    installAgent: (agentId: string, version?: string) =>
+      withLoading(() => agentMarketSdk.installAgent(agentId, version)),
+
+    uninstallAgent: (agentId: string) =>
+      withLoading(() => agentMarketSdk.uninstallAgent(agentId)),
+
+    checkUpdates: () =>
+      withLoading(() => agentMarketSdk.checkUpdates()),
+
+    isLoading,
+    lastError,
+  }
+}

package/renderer/hooks/use-agents-sdk.ts

@@ -0,0 +1,7 @@
+import { useTuffTransport } from '../../transport'
+import { createAgentsSdk } from '../../transport/sdk/domains/agents'
+
+export function useAgentsSdk() {
+  const transport = useTuffTransport()
+  return createAgentsSdk(transport)
+}

package/renderer/hooks/use-app-sdk.ts

@@ -0,0 +1,7 @@
+import { useTuffTransport } from '../../transport'
+import { createAppSdk } from '../../transport/sdk/domains/app'
+
+export function useAppSdk() {
+  const transport = useTuffTransport()
+  return createAppSdk(transport)
+}

package/renderer/hooks/use-channel.ts

@@ -1,5 +1,6 @@
 import type { InjectionKey } from 'vue'
 import { inject } from 'vue'
+import { hasWindow } from '../../env'
 
 export interface TouchChannel {
   send: <TRequest = any, TResponse = any>(
@@ -11,6 +12,16 @@ export interface TouchChannel {
     eventName: string,
     handler: (data: TRequest) => Promise<any> | any,
   ) => () => void
+
+  unRegChannel?: <TRequest = any>(
+    eventName: string,
+    handler: (data: TRequest) => Promise<any> | any,
+  ) => boolean
+
+  sendSync?: <TRequest = any, TResponse = any>(
+    eventName: string,
+    data?: TRequest,
+  ) => TResponse
 }
 
 // Injection key for the TouchChannel
@@ -26,8 +37,8 @@ declare global {
     $touchChannel?: TouchChannel
   }
 
-  var touchChannel: TouchChannel | undefined
-  var $touchChannel: TouchChannel | undefined
+  let touchChannel: TouchChannel | undefined
+  let $touchChannel: TouchChannel | undefined
 }
 
 /**
@@ -49,16 +60,18 @@ function resolveTouchChannel(): TouchChannel | null {
     const channel
       = (globalThis as any).touchChannel
         || (globalThis as any).$touchChannel
+        || (globalThis as any).$channel
         || (globalThis as any).window?.touchChannel
         || (globalThis as any).window?.$touchChannel
+        || (globalThis as any).window?.$channel
 
     if (channel)
       return channel
   }
 
   // Try window object (browser environment)
-  if (typeof window !== 'undefined') {
-    const channel = window.touchChannel || window.$touchChannel
+  if (hasWindow()) {
+    const channel = window.touchChannel || window.$touchChannel || (window as any).$channel
     if (channel)
       return channel
   }
@@ -107,6 +120,22 @@ export function useChannel(): TouchChannel {
   return channel
 }
 
+/**
+ * Safe version of useChannel that returns null instead of throwing
+ * when TouchChannel is not available. Useful for optional features.
+ *
+ * @example
+ * ```ts
+ * const channel = tryUseChannel()
+ * if (channel) {
+ *   const result = await channel.send('get-app-config')
+ * }
+ * ```
+ */
+export function tryUseChannel(): TouchChannel | null {
+  return resolveTouchChannel()
+}
+
 /**
  * Helper composable that creates a typed channel wrapper
  * for specific communication patterns

package/renderer/hooks/use-download-sdk.ts

@@ -0,0 +1,21 @@
+import { onUnmounted } from 'vue'
+import { useTuffTransport } from '../../transport'
+import { createDisposableBag } from '../../transport/sdk'
+import { createDownloadSdk } from '../../transport/sdk/domains/download'
+
+export function useDownloadSdk() {
+  const transport = useTuffTransport()
+  return createDownloadSdk(transport)
+}
+
+export function useDownloadSdkScope() {
+  const sdk = useDownloadSdk()
+  const disposables = createDisposableBag()
+  const register = (dispose: () => void) => {
+    disposables.add(dispose)
+    return dispose
+  }
+
+  onUnmounted(() => disposables.dispose())
+  return { sdk, disposables, register }
+}

package/renderer/hooks/use-intelligence-sdk.ts

@@ -0,0 +1,7 @@
+import { useTuffTransport } from '../../transport'
+import { createIntelligenceSdk } from '../../transport/sdk/domains/intelligence'
+
+export function useIntelligenceSdk() {
+  const transport = useTuffTransport()
+  return createIntelligenceSdk(transport)
+}