/**
 * MCP 工具签名 DTO
 * 详见 docs/modules/internal-app-platform/07-api.md §3
 */

// ============================================================================
// 通用结构
// ============================================================================

export interface McpSuccess<T> {
  ok: true;
  data: T;
  warning?: string;
}

export interface McpError {
  ok: false;
  error: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
    onboardUrl?: string;
  };
}

export type McpResult<T> = McpSuccess<T> | McpError;

// ============================================================================
// MCP 工具命名常量（控制器用 server.registerTool 逐个注册，SDK 接管 tools/call
// 与 tools/list 路由——协议入参类型不再需要本仓库定义）
// ============================================================================

export type McpToolName =
  | 'list_apps'
  | 'deploy_prepare'
  | 'logs'
  | 'env'
  | 'destroy';

// ============================================================================
// 工具具体 schema
// ============================================================================

/** list_apps */
export interface ListAppsInput {
  includeDestroyed?: boolean;
}

export interface ListAppsOutput {
  apps: Array<{
    id: string;
    appSlug: string;
    displayName: string | null;
    runtime: 'node' | 'static';
    status: string;
    url: string;
    lastDeployedAt: string | null;
    destroyedAt: string | null;
    retentionUntil: string | null;
  }>;
}

/** deploy_prepare */
export interface DeployPrepareInput {
  appSlug: string;
  displayName?: string;
  detected?: {
    hasPackageJson: boolean;
    hasStartScript: boolean;
    hasIndexHtml: boolean;
    hasDockerfile?: boolean;
    hasRequirementsTxt?: boolean;
    hasGoMod?: boolean;
    hasPomXml?: boolean;
  };
}

export interface DeployPrepareOutput {
  /**
   * InternalApp 行 id。Phase 0 阶段返回 null —— deploy_prepare 还未与 internal_apps 表绑定
   * （首次容器跑起后才 upsert），故此处显式 null 而不是零 UUID 占位（PR #396 AI Review §risk-4）。
   * Phase 0 中期接入"部署即建 InternalApp 行"后此处返真 UUID。
   */
  appId: string | null;
  isFirstDeploy: boolean;
  runtime: 'node' | 'static';
  repoUrl: string;
  pushCredential: {
    token: string;
    expiresAt: string;
  };
  branch: 'main';
  suggestedCommitMessage: string;
  url: string;
  /**
   * 给 Claude Code 的事后话术提示：push 完成后该怎么告知用户。
   * 平台 webhook → 构建 → 上线一般 30s–5min；Claude 应提示用户 5 分钟后再访问 url 或调 logs 查看构建结果，
   * 而不是立即声称"已部署成功"——push 完成 ≠ 上线完成。
   */
  postDeployHint: string;
}

/** logs */
export interface LogsInput {
  appSlug: string;
  lines?: number;
}

export interface LogsOutput {
  appSlug: string;
  runtime: 'node' | 'static';
  logs: string;
  truncated: boolean;
  fetchedAt: string;
}

/** env */
export type EnvAction = 'list' | 'get' | 'set' | 'unset';

export interface EnvInput {
  appSlug: string;
  action: EnvAction;
  key?: string;
  value?: string;
}

/** destroy */
export interface DestroyInput {
  appSlug: string;
  confirm: true;
}

export interface DestroyOutput {
  appSlug: string;
  status: 'DESTROYED';
  destroyedAt: string;
  retentionUntil: string;
  restoreInstruction: string;
}