/**
 * Plugin Manifest Schema Types
 *
 * Defines the schema types for plugin-provided manifest metadata.
 * Plugins export their state schema statically, avoiding runtime inference.
 */

import type { ActionContract } from "@gizmo-ai/runtime";

/**
 * JSON Schema definition (subset of JSON Schema Draft 2020-12)
 */
export interface JSONSchema {
  type?: string | string[];
  properties?: Record<string, JSONSchema>;
  items?: JSONSchema;
  required?: string[];
  $ref?: string;
  $defs?: Record<string, JSONSchema>;
  description?: string;
  enum?: unknown[];
  const?: unknown;
  default?: unknown;
  additionalProperties?: boolean | JSONSchema;
  [key: string]: unknown;
}

/**
 * UI metadata for a state slice
 *
 * Used by UI clients to display and categorize state slices.
 */
export interface SliceUIMetadata {
  /** Human-readable display name for the slice */
  displayName?: string;
  /** Description of what this slice represents */
  description?: string;
  /** Category for grouping in UI */
  category?: "core" | "agent" | "workflow" | "observability" | string;
  /** If true, hide from default UI views (internal/debug slices) */
  hidden?: boolean;
}

/**
 * Plugin capabilities declaration
 *
 * Declares what features and tools a plugin provides.
 */
export interface PluginCapabilities {
  /** Feature flags the plugin enables */
  features?: string[];
  /** Tool names the plugin provides */
  tools?: string[];
  /** Whether the plugin supports streaming */
  streaming?: boolean;
}

/**
 * Plugin manifest schema
 *
 * Exported by each plugin to provide static metadata for manifest generation.
 * This replaces runtime state inference with explicit schema declarations.
 *
 * @example
 * ```typescript
 * // packages/agent-plugin/src/manifest.ts
 * import type { PluginManifestSchema } from "@gizmo-ai/server";
 *
 * export const AgentManifestSchema: PluginManifestSchema = {
 *   pluginKey: "agent",
 *   version: "0.1.0",
 *   stateSchema: {
 *     type: "object",
 *     properties: {
 *       conversation: { ... },
 *       tools: { ... },
 *     }
 *   },
 *   uiMetadata: {
 *     displayName: "Agent",
 *     category: "agent",
 *   },
 *   capabilities: {
 *     features: ["streaming", "tool_execution"],
 *     streaming: true,
 *   },
 * };
 * ```
 */
export interface PluginManifestSchema {
  /** Plugin key (matches state slice key) */
  pluginKey: string;

  /** Plugin version */
  version: string;

  /** JSON Schema for the plugin's state slice */
  stateSchema?: JSONSchema;

  /** UI metadata for display */
  uiMetadata?: SliceUIMetadata;

  /** Plugin capabilities */
  capabilities?: PluginCapabilities;

  /** Action contract (for documentation and discovery) */
  contract?: ActionContract;

  /** Route paths this plugin exposes (e.g., ["/approvals", "/approvals/:id"]) */
  routes?: string[];
}