Script-Runtime

import {
  // 类型导出
  type ProxyCommand,
  type ProxyContext,
  type ProxyDefinition,
  type ProxyMatcherConfig,
  type ProxyModule,
  type ProxyModuleConfig,
  type ProxyRouteHandler,
  type ValidatePublicPathOptions,
 
  // 函数导出
  defineProxy,
  loadProxyModule,
  validatePublicPath,
  resolvePublicPath,
  resolvePublicPathUnchecked,
  getProxyModuleConfig
} from '@truenine/memory-sync-sdk'

function defineProxy<T extends ProxyDefinition | ProxyRouteHandler>(value: T): T

async function loadProxyModule(filePath: string): Promise<ProxyModule>

function validatePublicPath(
  resolvedPath: string,
  options: ValidatePublicPathOptions
): string

function resolvePublicPath(
  filePath: string,
  ctx: ProxyContext,
  logicalPath: string,
  timeoutMs?: number = 5_000
): string

async function resolvePublicPathUnchecked(
  filePath: string,
  ctx: ProxyContext,
  logicalPath: string
): Promise<string>

function getProxyModuleConfig(module: ProxyModule): ProxyModuleConfig | undefined

interface ProxyContext {
  readonly cwd: string           // 当前工作目录
  readonly workspaceDir: string   // 工作区根目录
  readonly aindexDir: string      // Aindex 数据目录
  readonly command: ProxyCommand  // 当前执行的命令
  readonly platform: NodeJS.Platform  // 运行平台
}

interface ValidatePublicPathOptions {
  readonly aindexPublicDir: string  // Aindex 公共资源根目录，用作安全边界
}

type ProxyCommand = 'install' | 'dry-run' | 'clean' | 'plugins'

interface ProxyMatcherConfig {
  readonly commands?: readonly ProxyCommand[]  // 生效的命令列表，空或未设置表示全部生效
}

// 代理模块的完整结构
interface ProxyModule {
  readonly default: ProxyHandler          // 默认导出：函数或定义对象
  readonly config?: ProxyModuleConfig     // 可选的模块配置
}
 
// 模块配置
interface ProxyModuleConfig {
  readonly matcher?: ProxyMatcherConfig   // 命令匹配器
}
 
// 代理定义对象形式
interface ProxyDefinition {
  readonly resolvePublicPath?: ProxyRouteHandler  // 路径解析处理器
}
 
// 路由处理函数签名
type ProxyRouteHandler = (
  logicalPath: string,
  ctx: ProxyContext
) => string | Promise<string>

Usage: resolve-proxy-worker <file-path> <ctx-json-path> <logical-path>

pub fn validate_public_path_impl(
    resolved_path: &str,
    aindex_public_dir: &str,
) -> Result<String, String>

pub fn resolve_public_path_impl(
    file_path: &str,
    ctx_json: &str,
    logical_path: &str,
) -> Result<String, String>

// project/proxy.ts
import {defineProxy, type ProxyRouteHandler} from '@truenine/memory-sync-sdk'
 
const handler: ProxyRouteHandler = (logicalPath) => {
  // 简单的前缀映射
  return `public/${logicalPath}`
}
 
export default defineProxy(handler)

import {loadProxyModule, getProxyModuleConfig} from '@truenine/memory-sync-sdk'
 
async function useExternalProxy(proxyPath: string) {
  // 加载代理模块
  const module = await loadProxyModule(proxyPath)
 
  // 获取模块配置
  const config = getProxyModuleConfig(module)
  console.log('Matcher commands:', config?.matcher?.commands)
 
  // 直接调用默认导出的处理器（如果是函数形式）
  if (typeof module.default === 'function') {
    const result = await module.default('styles/main.css', {
      cwd: process.cwd(),
      workspaceDir: '/path/to/workspace',
      aindexDir: '/path/to/.aindex',
      command: 'install',
      platform: process.platform
    })
    console.log('Resolved:', result)
  }
}
 
useExternalProxy('./project/proxy.ts')

import {validatePublicPath} from '@truenine/memory-sync-sdk'
 
const options = {aindexPublicDir: '/workspace/.aindex/public'}
 
// ✅ 合法的相对路径
const valid = validatePublicPath('assets/images/logo.png', options)
console.log(valid) // "assets/images/logo.png"
 
try {
  // ❌ 绝对路径 - 会抛出错误
  validatePublicPath('/etc/passwd', options)
} catch (error) {
  console.error('Rejected absolute path:', error.message)
}
 
try {
  // ❌ 路径遍历 - 会抛出错误
  validatePublicPath('../../secret.txt', options)
} catch (error) {
  console.error('Rejected traversal:', error.message)
}
 
try {
  // ❌ 包含反斜杠的父目录引用
  validatePublicPath('safe\\..\\..\\escape', options)
} catch (error) {
  console.error('Rejected backslash traversal:', error.message)
}

import {resolvePublicPath} from '@truenine/memory-sync-sdk'
 
const ctx = {
  cwd: '/home/user/project',
  workspaceDir: '/home/user/project',
  aindexDir: '/home/user/project/.aindex',
  command: 'install' as const,
  platform: process.platform
}
 
// 完整的端到端解析（同步，带超时保护）
try {
  const result = resolvePublicPath(
    './proxy.ts',     // 代理模块路径
    ctx,              // 代理上下文
    'scripts/app.js', // 逻辑路径
    10_000            // 自定义超时 10 秒
  )
  console.log('Safely resolved:', result)
} catch (error) {
  if (error.message.includes('timed out')) {
    console.error('代理模块执行超时')
  } else {
    console.error('路径解析失败:', error.message)
  }
}

// project/proxy.ts - 生产级代理模块
import {
  defineProxy,
  type ProxyDefinition,
  type ProxyRouteHandler,
  type ProxyContext,
  type ProxyModuleConfig
} from '@truenine/memory-sync-sdk'
import {join, extname} from 'node:path'
 
/**
 * 根据文件扩展名选择不同的路径映射策略
 */
const resolveHandler: ProxyRouteHandler = async (
  logicalPath: string,
  ctx: ProxyContext
): Promise<string> => {
  const ext = extname(logicalPath)
 
  switch (ext) {
    case '.ts':
    case '.tsx':
    case '.js':
    case '.jsx':
      // 脚本文件映射到 dist 目录
      return join('dist', logicalPath)
 
    case '.css':
    case '.less':
    case '.scss':
      // 样式文件映射到 assets/styles
      return join('assets', 'styles', logicalPath)
 
    case '.png':
    case '.jpg':
    case '.svg':
    case '.webp':
      // 图片资源根据平台分目录
      return join('assets', 'images', ctx.platform, logicalPath)
 
    default:
      // 其他文件保持原路径
      return logicalPath
  }
}
 
const definition: ProxyDefinition = {
  resolvePublicPath: resolveHandler
}
 
export default defineProxy(definition)
 
export const config: ProxyModuleConfig = {
  matcher: {
    // 仅在 install 和 dry-run 命令下生效
    commands: ['install', 'dry-run']
  }
}

import {resolvePublicPath, loadProxyModule, getProxyModuleConfig} from '@truenine/memory-sync-sdk'
 
async function demonstrateFullProxy() {
  const ctx = {
    cwd: process.cwd(),
    workspaceDir: process.cwd(),
    aindexDir: join(process.cwd(), '.aindex'),
    command: 'install' as const,
    platform: process.platform
  }
 
  // 方式一：使用完整的 resolvePublicPath（含 Rust 安全验证）
  const scriptPath = resolvePublicPath('./project/proxy.ts', ctx, 'utils/helper.ts')
  console.log('Script path:', scriptPath)
  // 输出类似: "dist/utils/helper.ts"
 
  const imagePath = resolvePublicPath('./project/proxy.ts', ctx, 'logo.png')
  console.log('Image path:', imagePath)
  // 输出类似: "assets/images/linux-x64/logo.png"
 
  // 方式二：先加载模块查看配置
  const module = await loadProxyModule('./project/proxy.ts')
  const moduleConfig = getProxyModuleConfig(module)
  console.log('Active commands:', moduleConfig?.matcher?.commands)
  // 输出: ["install", "dry-run"]
}

project/
├── proxy.ts              # 代理模块入口（必须）
├── src/
│   └── resolvers/        # 自定义解析器（可选）
│       ├── asset-resolver.ts
│       └── path-utils.ts
└── tsconfig.json         # TypeScript 配置（可选）

import {resolvePublicPath, loadProxyModule} from '@truenine/memory-sync-sdk'
 
class ProxyResolutionError extends Error {
  constructor(
    message: string,
    public readonly phase: 'load' | 'execute' | 'validate',
    public readonly cause?: Error
  ) {
    super(message)
    this.name = 'ProxyResolutionError'
  }
}
 
async function safeResolve(
  proxyPath: string,
  ctx: Parameters<typeof resolvePublicPath>[1],
  logicalPath: string
): Promise<string> {
  try {
    // 预检：确保代理模块可以正常加载
    await loadProxyModule(proxyPath)
  } catch (error) {
    throw new ProxyResolutionError(
      `无法加载代理模块: ${proxyPath}`,
      'load',
      error instanceof Error ? error : undefined
    )
  }
 
  try {
    // 正式解析（带合理的超时）
    return resolvePublicPath(proxyPath, ctx, logicalPath, 15_000)
  } catch (error) {
    const message = error instanceof Error ? error.message : String(error)
    if (message.includes('timed out')) {
      throw new ProxyResolutionError(
        `代理模块执行超时: ${proxyPath}`,
        'execute',
        error instanceof Error ? error : undefined
      )
    }
    throw new ProxyResolutionError(
      `路径验证失败: ${message}`,
      'validate',
      error instanceof Error ? error : undefined
    )
  }
}

// ❌ 错误：直接使用 unchecked 结果访问文件系统
import {readFile} from 'node:fs/promises'
import {resolvePublicPathUnchecked} from '@truenine/memory-sync-sdk'
 
const unsafePath = await resolvePublicPathUnchecked(proxyPath, ctx, userInput)
const content = await readFile(unsafePath, 'utf8') // 危险！未经验证
 
// ✅ 正确：始终经过验证
import {resolvePublicPath} from '@truenine/memory-sync-sdk'
import {readFile} from 'node:fs/promises'
 
const safePath = resolvePublicPath(proxyPath, ctx, userInput) // 含 Rust 验证
const content = await readFile(join(publicRoot, safePath), 'utf8') // 安全