sudocode 1.1.16 → 1.1.18-dev.0

package/node_modules/@sudocode-ai/types/src/integrations.d.ts

@@ -0,0 +1,454 @@
+/**
+ * Integration plugin types for sudocode
+ *
+ * This module defines the plugin interface for external integrations.
+ * Provider-specific implementations should be in separate packages.
+ */
+
+import type {
+  SyncDirection,
+  ConflictResolution,
+  Spec,
+  Issue,
+} from "./index.js";
+
+// =============================================================================
+// Plugin Configuration
+// =============================================================================
+
+/**
+ * Base configuration for any integration provider
+ * Provider-specific options go in the `options` field
+ */
+export interface IntegrationProviderConfig {
+  /** npm package name or local path to the plugin */
+  plugin?: string;
+  /** Whether this integration is enabled */
+  enabled: boolean;
+  /** Whether to automatically sync changes (default: false) */
+  auto_sync?: boolean;
+  /** Default sync direction for new links (default: 'bidirectional') */
+  default_sync_direction?: SyncDirection;
+  /** How to resolve sync conflicts (default: 'manual') */
+  conflict_resolution?: ConflictResolution;
+  /**
+   * Whether to auto-import new entities from external system (default: true)
+   * When true, new issues/specs in the external system are automatically
+   * created as sudocode issues/specs with an external_link.
+   */
+  auto_import?: boolean;
+  /**
+   * What to do when an external entity is deleted (default: 'close')
+   * - 'close': Close the linked sudocode issue (set status to 'closed')
+   * - 'delete': Delete the linked sudocode issue entirely
+   * - 'ignore': Do nothing, leave sudocode issue unchanged
+   */
+  delete_behavior?: "close" | "delete" | "ignore";
+  /** Provider-specific configuration options */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * Top-level integrations configuration object
+ * Maps provider names to their configurations
+ */
+export interface IntegrationsConfig {
+  [providerName: string]: IntegrationProviderConfig | undefined;
+}
+
+// =============================================================================
+// Plugin Interface
+// =============================================================================
+
+/**
+ * Validation result from plugin
+ */
+export interface PluginValidationResult {
+  /** Whether the configuration is valid (no blocking errors) */
+  valid: boolean;
+  /** Blocking errors that prevent the plugin from working */
+  errors: string[];
+  /** Non-blocking warnings about the configuration */
+  warnings: string[];
+}
+
+/**
+ * Result from testing a plugin's connection/setup
+ */
+export interface PluginTestResult {
+  /** Whether the test passed */
+  success: boolean;
+  /** Whether the plugin is configured */
+  configured: boolean;
+  /** Whether the plugin is enabled */
+  enabled: boolean;
+  /** Error message if test failed */
+  error?: string;
+  /** Additional details about the test */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * JSON Schema for UI form generation (subset of JSON Schema)
+ */
+export interface PluginConfigSchema {
+  type: "object";
+  properties: Record<
+    string,
+    {
+      type: "string" | "boolean" | "number" | "array";
+      title?: string;
+      description?: string;
+      default?: unknown;
+      enum?: unknown[];
+      required?: boolean;
+    }
+  >;
+  required?: string[];
+}
+
+/**
+ * Interface that all integration plugins must implement
+ *
+ * Plugins are loaded dynamically and must export an object conforming to this interface.
+ *
+ * @example
+ * ```typescript
+ * // In @sudocode-ai/integration-beads/src/index.ts
+ * import type { IntegrationPlugin } from '@sudocode-ai/types';
+ *
+ * const plugin: IntegrationPlugin = {
+ *   name: 'beads',
+ *   displayName: 'Beads',
+ *   version: '1.0.0',
+ *   // ... implement required methods
+ * };
+ *
+ * export default plugin;
+ * ```
+ */
+export interface IntegrationPlugin {
+  /** Unique plugin identifier (used as key in config) */
+  name: string;
+  /** Human-readable display name */
+  displayName: string;
+  /** Plugin version */
+  version: string;
+  /** Plugin description */
+  description?: string;
+
+  // ===========================================================================
+  // Configuration
+  // ===========================================================================
+
+  /**
+   * JSON Schema describing the plugin's options
+   * Used by UI to generate configuration forms
+   */
+  configSchema?: PluginConfigSchema;
+
+  /**
+   * Validate plugin configuration
+   * Called before saving config and before starting sync
+   *
+   * @param options - The plugin-specific options from config
+   * @returns Validation result with errors and warnings
+   */
+  validateConfig(options: Record<string, unknown>): PluginValidationResult;
+
+  /**
+   * Test the plugin's connection/setup
+   * Called when user clicks "Test" button in UI
+   *
+   * @param options - The plugin-specific options from config
+   * @param projectPath - Path to the sudocode project root
+   * @returns Test result with success status and details
+   */
+  testConnection(
+    options: Record<string, unknown>,
+    projectPath: string
+  ): Promise<PluginTestResult>;
+
+  // ===========================================================================
+  // Provider Factory
+  // ===========================================================================
+
+  /**
+   * Create an IntegrationProvider instance for sync operations
+   *
+   * @param options - The plugin-specific options from config
+   * @param projectPath - Path to the sudocode project root
+   * @returns Provider instance ready for sync operations
+   */
+  createProvider(
+    options: Record<string, unknown>,
+    projectPath: string
+  ): IntegrationProvider;
+}
+
+// =============================================================================
+// Provider Interface (for sync operations)
+// =============================================================================
+
+/**
+ * Represents an entity from an external system
+ * Normalized structure for cross-provider compatibility
+ */
+/**
+ * Represents a relationship from this entity to another
+ */
+export interface ExternalRelationship {
+  /** Target entity ID in the external system */
+  targetId: string;
+  /** Target entity type */
+  targetType: "spec" | "issue";
+  /** Relationship type */
+  relationshipType: "implements" | "blocks" | "depends-on" | "references" | "related" | "discovered-from";
+}
+
+export interface ExternalEntity {
+  /** Unique identifier in the external system */
+  id: string;
+  /** Entity type (maps to sudocode spec or issue) */
+  type: "spec" | "issue";
+  /** Entity title */
+  title: string;
+  /** Entity description/content (optional) */
+  description?: string;
+  /** Status in external system (optional) */
+  status?: string;
+  /** Priority level (optional, 0-4 scale like sudocode) */
+  priority?: number;
+  /** URL to view in external system (optional) */
+  url?: string;
+  /** When created in external system (optional, ISO 8601) */
+  created_at?: string;
+  /** When last updated in external system (optional, ISO 8601) */
+  updated_at?: string;
+  /** Relationships from this entity to other entities (optional) */
+  relationships?: ExternalRelationship[];
+  /** Raw data from external system (for provider-specific handling) */
+  raw?: unknown;
+}
+
+/**
+ * Options for searching entities
+ */
+export interface SearchOptions {
+  /** Repository to search in (e.g., "owner/repo") */
+  repo?: string;
+  /** Page number for pagination (1-indexed) */
+  page?: number;
+  /** Number of results per page */
+  perPage?: number;
+}
+
+/**
+ * Result of a search operation with pagination info
+ */
+export interface SearchResult {
+  /** List of matching entities */
+  results: ExternalEntity[];
+  /** Pagination info */
+  pagination?: {
+    page: number;
+    perPage: number;
+    hasMore: boolean;
+    totalCount?: number;
+  };
+}
+
+/**
+ * Represents a comment from an external system
+ * Used for importing discussion threads alongside entities
+ */
+export interface ExternalComment {
+  /** Unique identifier in the external system */
+  id: string;
+  /** Comment author (username or display name) */
+  author: string;
+  /** Comment body/content */
+  body: string;
+  /** When the comment was created (ISO 8601) */
+  created_at: string;
+  /** URL to view the comment in external system (optional) */
+  url?: string;
+}
+
+/**
+ * Interface for providers that support on-demand import
+ * Implement this interface to enable URL-based import capabilities
+ */
+export interface OnDemandImportCapable {
+  /**
+   * Check if this provider can handle the given URL
+   * @param url - URL to check
+   * @returns true if this provider can import from this URL
+   */
+  canHandleUrl?(url: string): boolean;
+
+  /**
+   * Parse a URL to extract entity information
+   * @param url - URL to parse
+   * @returns Parsed entity info or null if URL cannot be parsed
+   */
+  parseUrl?(url: string): { externalId: string; metadata?: Record<string, unknown> } | null;
+
+  /**
+   * Fetch an entity by its URL
+   * @param url - URL to fetch from
+   * @returns The external entity or null if not found
+   */
+  fetchByUrl?(url: string): Promise<ExternalEntity | null>;
+
+  /**
+   * Refresh multiple entities by their external IDs
+   * @param externalIds - Array of external IDs to refresh
+   * @returns Array of entities (null for any that couldn't be fetched)
+   */
+  refreshEntities?(externalIds: string[]): Promise<(ExternalEntity | null)[]>;
+
+  /**
+   * Fetch comments for an entity
+   * @param externalId - External ID of the entity
+   * @returns Array of comments
+   */
+  fetchComments?(externalId: string): Promise<ExternalComment[]>;
+}
+
+/**
+ * Represents a change detected in an external system
+ * Used for incremental sync operations
+ */
+export interface ExternalChange {
+  /** Entity ID that changed */
+  entity_id: string;
+  /** Type of entity that changed */
+  entity_type: "spec" | "issue";
+  /** Type of change */
+  change_type: "created" | "updated" | "deleted";
+  /** When the change occurred (ISO 8601) */
+  timestamp: string;
+  /** The entity data (present for created/updated, absent for deleted) */
+  data?: ExternalEntity;
+}
+
+/**
+ * Result of a sync operation for a single entity
+ */
+export interface SyncResult {
+  /** Whether the sync operation succeeded */
+  success: boolean;
+  /** Sudocode entity ID */
+  entity_id: string;
+  /** External system entity ID */
+  external_id: string;
+  /** What action was taken */
+  action: "created" | "updated" | "skipped" | "conflict";
+  /** Error message if sync failed (optional) */
+  error?: string;
+}
+
+/**
+ * Represents a sync conflict between sudocode and external system
+ */
+export interface SyncConflict {
+  /** Sudocode entity ID */
+  sudocode_entity_id: string;
+  /** External system entity ID */
+  external_id: string;
+  /** Integration provider name */
+  provider: string;
+  /** When sudocode entity was last updated (ISO 8601) */
+  sudocode_updated_at: string;
+  /** When external entity was last updated (ISO 8601) */
+  external_updated_at: string;
+}
+
+/**
+ * Interface for sync operations with an external system
+ *
+ * Created by IntegrationPlugin.createProvider()
+ */
+export interface IntegrationProvider {
+  /** Provider name (matches plugin name) */
+  readonly name: string;
+  /** Whether this provider supports real-time watching for changes */
+  readonly supportsWatch: boolean;
+  /** Whether this provider supports polling for changes */
+  readonly supportsPolling: boolean;
+  /** Whether this provider supports on-demand import via URL */
+  readonly supportsOnDemandImport: boolean;
+  /** Whether this provider supports search operations */
+  readonly supportsSearch: boolean;
+  /** Whether this provider supports pushing changes to external system */
+  readonly supportsPush: boolean;
+
+  // ===========================================================================
+  // Lifecycle
+  // ===========================================================================
+
+  /** Initialize the provider (called once before sync operations) */
+  initialize(): Promise<void>;
+
+  /** Clean up resources when the provider is no longer needed */
+  dispose(): Promise<void>;
+
+  // ===========================================================================
+  // Entity Operations
+  // ===========================================================================
+
+  /** Fetch a single entity from the external system */
+  fetchEntity(externalId: string): Promise<ExternalEntity | null>;
+
+  /** Search for entities in the external system */
+  searchEntities(
+    query?: string,
+    options?: SearchOptions
+  ): Promise<ExternalEntity[] | SearchResult>;
+
+  /** Create a new entity in the external system */
+  createEntity(entity: Partial<Spec | Issue>): Promise<string>;
+
+  /** Update an existing entity in the external system */
+  updateEntity(
+    externalId: string,
+    entity: Partial<Spec | Issue>
+  ): Promise<void>;
+
+  /** Delete an entity from the external system (optional) */
+  deleteEntity?(externalId: string): Promise<void>;
+
+  // ===========================================================================
+  // Change Detection
+  // ===========================================================================
+
+  /** Get changes since a timestamp (for polling) */
+  getChangesSince(timestamp: Date): Promise<ExternalChange[]>;
+
+  /** Start watching for real-time changes (optional) */
+  startWatching?(callback: (changes: ExternalChange[]) => void): void;
+
+  /** Stop watching for real-time changes (optional) */
+  stopWatching?(): void;
+
+  // ===========================================================================
+  // Field Mapping
+  // ===========================================================================
+
+  /** Map an external entity to sudocode format */
+  mapToSudocode(external: ExternalEntity): {
+    spec?: Partial<Spec>;
+    issue?: Partial<Issue>;
+  };
+
+  /** Map a sudocode entity to external format */
+  mapFromSudocode(entity: Spec | Issue): Partial<ExternalEntity>;
+}
+
+// =============================================================================
+// Legacy Exports (for backwards compatibility during migration)
+// =============================================================================
+
+/** @deprecated Use IntegrationProviderConfig instead */
+export type IntegrationConfig = IntegrationProviderConfig;