import type { DetectedClient } from './detect.js';

export interface CatalogModel {
  id: string;
  name?: string;
  context_window?: number | null;
  context_length?: number | null;
  available?: boolean;
}

export interface GeneratedFile {
  path: string;
  format: 'json' | 'toml' | 'yaml' | 'env';
  /** Structured patch, deep-merged into the existing document (json, yaml). */
  value?: Record<string, unknown>;
  /** Literal text, merged as a marked `# freellmapi:start/end` block (toml, yaml, env). */
  content?: string;
  sensitive?: boolean;
  /** json only: arrays merged item by item instead of replaced whole, keyed by
   *  the array's dotted path. `ownedBy` drops the existing items whose fields
   *  all match it, then appends the patch's items; `union` keeps the existing
   *  values and appends the patch's missing ones. */
  arrays?: Record<string, JsonArrayMerge>;
}

export type JsonArrayMerge = { ownedBy: Record<string, string> } | { union: true };

export interface GenerateContext {
  url: string;
  apiKey: string;
  profile: string;
  models: CatalogModel[];
  homeDir: string;
  /** An explicit `--model`. Overrides each generator's default-model
   *  heuristic; validated against the unfiltered catalog by the caller. */
  requestedModelId?: string;
  /** Result of `detectChatGptClient()`. Injected by the CLI entry point;
   *  when the property is absent generators probe the real machine, which
   *  golden-output tests must avoid (the snapshot must not depend on the
   *  host's installed clients). */
  detectedClient?: DetectedClient;
}

export interface Generation {
  files: GeneratedFile[];
  notes: string[];
}

export interface ToolDefinition {
  id: string;
  name: string;
  category: 'code' | 'agent';
  configType: 'env' | 'file' | 'guide';
  protocol: string;
  baseUrlSupport: 'root' | '/v1';
  command: string;
  docsUrl: string;
  generate(ctx: GenerateContext): Generation;
}