/**
 * 通用模板引擎 - 类型定义
 *
 * 支持动态变量替换和条件表达式的模板系统
 */

/**
 * 模板函数类型
 * 无参数函数，返回字符串或数字
 */
export type TemplateFunction = () => string | number;

/**
 * 模板函数注册表
 * 用于存储可在模板中调用的函数
 */
export type TemplateFunctionRegistry = Record<string, TemplateFunction>;

/**
 * 模板上下文 - 运行时可用的变量
 *
 * 支持任意嵌套的键值对结构
 */
export type TemplateContext = Record<string, unknown>;

/**
 * 扩展的模板上下文 - 支持函数调用
 *
 * 除了普通变量外，还支持通过 __functions__ 注册可调用的函数
 */
export interface ExtendedTemplateContext extends Record<string, unknown> {
  /** 注册的模板函数 */
  __functions__?: TemplateFunctionRegistry;
}

/**
 * 模板定义
 */
export interface Template {
  /** 模板名称 */
  name: string;
  /** 模板描述 */
  description?: string;
  /** 模板内容（支持变量插值） */
  template: string;
  /** 所需变量列表（用于验证） */
  requiredVariables?: string[];
}

/**
 * 模板渲染选项
 */
export interface RenderOptions {
  /** 遇到未定义变量时是否抛出错误 */
  throwOnUndefined?: boolean;
  /** 未定义变量的默认值 */
  undefinedValue?: string;
  /** 是否启用调试日志 */
  debug?: boolean;
}

// ============================================
// Agent 特定类型（Prompt Template）
// ============================================

/**
 * 工具名称映射
 * 用于在模板中引用工具名称，便于重命名
 */
export interface ToolNameMapping {
  glob: string;
  grep: string;
  read: string;
  write: string;
  edit: string;
  bash: string;
  askUserQuestion: string;
  exitPlanMode: string;
  enterPlanMode: string;
  task: string;
  todoRead: string;
  todoWrite: string;
  webSearch: string;
  webExtract: string;
  gitStatus: string;
  gitDiff: string;
  gitLog: string;
  gitBranch: string;
  repoMap: string;
}

/**
 * Plan 模式上下文
 */
export interface PlanModeContext {
  /** 是否处于 Plan 模式 */
  isActive: boolean;
  /** 计划文件是否存在 */
  planExists: boolean;
  /** 计划文件路径 */
  planFilePath: string;
  /** 允许写入的路径列表 */
  allowedWritePaths: string[];
}

/**
 * 环境信息上下文
 */
export interface EnvContext {
  /** 工作目录 */
  workdir: string;
  /** 是否是 Git 仓库 */
  isGitRepo: boolean;
  /** 操作系统平台 */
  platform: string;
  /** 当前日期 */
  date: string;
  /** 主目录 */
  homeDir: string;
}

/**
 * Agent 信息上下文
 */
export interface AgentContext {
  /** Agent 名称 */
  name: string;
  /** Agent 模式 */
  mode: 'primary' | 'subagent' | 'all' | 'internal';
  /** 是否是子代理 */
  isSubagent: boolean;
}

/**
 * 提示词模板上下文 - 运行时可用的变量
 */
export interface PromptContext {
  /** 工具名称映射 */
  tools: ToolNameMapping;

  /** Plan 模式相关 */
  plan: PlanModeContext;

  /** 环境信息 */
  env: EnvContext;

  /** Agent 信息 */
  agent: AgentContext;

  /** 自定义扩展变量 */
  custom?: Record<string, unknown>;
}

/**
 * 提示词模板定义（继承自通用 Template）
 */
export interface PromptTemplate extends Template {}
