import type { CapabilityHandler } from "./types";

/**
 * 能力结构化元数据（任务 4.1，决策点 8：meta 可选 + 新能力强制）。
 * 老能力逐步补齐；规范 v1 验收 checklist 对新能力要求必填。
 */
export interface CapabilityParamMeta {
  key: string;
  label?: string;
  type: "string" | "number" | "boolean" | "object" | "array";
  required?: boolean;
  defaultValue?: string | number | boolean | null;
  description?: string;
}

/** 平台类型；现阶段只有 win32 有实现，darwin/linux 仅类型占位（dev-conventions 规则 4） */
export type CapabilityPlatform = "win32" | "darwin" | "linux";

export interface CapabilityMeta {
  /** 一句话能力摘要（中文） */
  summary?: string;
  /** 参数 schema（按字段名列出） */
  params?: CapabilityParamMeta[];
  /** 返回值说明 */
  returns?: string;
  /** 默认超时毫秒（无外部交互语义的能力省略） */
  timeoutMs?: number;
  /** 可能抛出的稳定错误码（见 engine/error-codes.ts） */
  errorCodes?: string[];
  /** 执行中是否需要回传截图（Agent 侧视觉判断用） */
  needsScreenshot?: boolean;
  /** 平台限制；省略表示跨平台 */
  platforms?: CapabilityPlatform[];
}

const handlers = new Map<string, CapabilityHandler>();
const metas = new Map<string, CapabilityMeta>();

export function register(ids: string | string[], handler: CapabilityHandler, meta?: CapabilityMeta): void {
  const list = Array.isArray(ids) ? ids : [ids];
  for (const id of list) {
    handlers.set(id, handler);
    if (meta) metas.set(id, meta);
  }
}

export function getHandler(id: string): CapabilityHandler | undefined {
  return handlers.get(id);
}

export function getCapabilityMeta(id: string): CapabilityMeta | undefined {
  return metas.get(id);
}

export function hasCapability(id: string): boolean {
  return handlers.has(id);
}

export function capabilityIds(): string[] {
  return [...handlers.keys()];
}

export function capabilityCount(): number {
  return handlers.size;
}

/**
 * 给一批能力落平台默认值（来自 register-all.ts 的 PLATFORM_GROUPS 单一权威表）。
 * - 空数组 = 平台无限制，不落 meta；
 * - 已有 meta 且已声明 platforms 的不覆盖（能力可显式声明更窄的平台限制）；
 * - 无 meta 的补一个只含 platforms 的 meta。
 */
export function applyPlatformDefaults(ids: string[], platforms: CapabilityPlatform[]): void {
  if (!platforms.length) return;
  for (const id of ids) {
    const meta = metas.get(id);
    if (meta) {
      if (!meta.platforms) metas.set(id, { ...meta, platforms: [...platforms] });
    } else {
      metas.set(id, { platforms: [...platforms] });
    }
  }
}