@deimoscloud/coreai 0.1.0

package/src/adapters/index.ts

@@ -0,0 +1,113 @@
+/**
+ * Adapters Module
+ *
+ * Provides adapter interfaces and factory for integrating with external services.
+ */
+
+// Types
+export type {
+  AdapterType,
+  AdapterImplementation,
+  AdapterInfo,
+  IssueStatus,
+  PullRequestStatus,
+  ReviewDecision,
+  Issue,
+  CreateIssueData,
+  UpdateIssueData,
+  IssueQuery,
+  PullRequest,
+  CreatePullRequestData,
+  PullRequestQuery,
+  Review,
+  CreateReviewData,
+  ReviewComment,
+  DocumentationPage,
+  DocumentationQuery,
+  StateEntry,
+  StateOptions,
+  AdapterErrorCode,
+} from './types.js';
+
+export { AdapterError } from './types.js';
+
+// Interfaces
+export type {
+  BaseAdapter,
+  IssueTrackerAdapter,
+  GitProviderAdapter,
+  DocumentationProviderAdapter,
+  StateProviderAdapter,
+  Adapter,
+} from './interfaces.js';
+
+// Factory
+export type { AdapterFactoryOptions } from './factory.js';
+
+export { AdapterFactory, createAdapterFactory, createAdapterInfo } from './factory.js';
+
+// MCP Integration
+export type {
+  McpTransportType,
+  StdioServerConfig,
+  HttpServerConfig,
+  McpServerConfig,
+  McpServerDefinition,
+  McpConfigFile,
+  McpServerInfo,
+  McpCapabilities,
+  McpTool,
+  McpResource,
+  McpToolResult,
+  McpContent,
+  McpTextContent,
+  McpImageContent,
+  McpResourceContent,
+  McpErrorCode,
+  McpClientOptions,
+  DiscoveryOptions,
+  ToolMapping,
+  ServerMapping,
+  ServerEntry,
+  ServerStatus,
+  RegistryEvents,
+  RegistryOptions,
+  ServerStatusSummary,
+  RegistryStatus,
+} from './mcp/index.js';
+
+export {
+  McpError,
+  McpClient,
+  createMockMcpClient,
+  discoverMcpServers,
+  loadServersFromFile,
+  parseServersFromConfig,
+  validateServerConfig,
+  findMcpConfigFile,
+  getDefaultMcpConfigPath,
+  findKnownServerMappings,
+  autoDiscoverMappings,
+  getMappingsForServer,
+  groupMappingsByAdapter,
+  McpRegistry,
+  createRegistry,
+} from './mcp/index.js';
+
+// Native Adapters
+export type {
+  FilesystemAdapterOptions,
+  GitHubAdapterOptions,
+  NativeAdapterSelectorOptions,
+  NativeAdapterAvailability,
+} from './native/index.js';
+
+export {
+  FilesystemAdapter,
+  createFilesystemAdapter,
+  GitHubAdapter,
+  createGitHubAdapter,
+  registerNativeAdapters,
+  checkNativeAdapterAvailability,
+  parseGitHubRemote,
+} from './native/index.js';

package/src/adapters/interfaces.ts

@@ -0,0 +1,268 @@
+/**
+ * Adapter Interfaces
+ *
+ * Abstract interfaces for integration adapters that can be implemented
+ * via MCP servers or native API clients.
+ */
+
+import type {
+  AdapterInfo,
+  Issue,
+  IssueQuery,
+  CreateIssueData,
+  UpdateIssueData,
+  IssueStatus,
+  PullRequest,
+  PullRequestQuery,
+  CreatePullRequestData,
+  Review,
+  CreateReviewData,
+  DocumentationPage,
+  DocumentationQuery,
+  StateEntry,
+  StateOptions,
+} from './types.js';
+
+/**
+ * Base interface that all adapters implement
+ */
+export interface BaseAdapter {
+  /**
+   * Get adapter metadata
+   */
+  getInfo(): AdapterInfo;
+
+  /**
+   * Check if the adapter is connected and available
+   */
+  isConnected(): boolean;
+
+  /**
+   * Connect to the service (if needed)
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Disconnect from the service
+   */
+  disconnect(): Promise<void>;
+}
+
+/**
+ * Issue Tracker Adapter
+ *
+ * For integrating with issue tracking systems like Jira, Linear, GitHub Issues, etc.
+ */
+export interface IssueTrackerAdapter extends BaseAdapter {
+  /**
+   * Get a single issue by ID or key
+   */
+  getIssue(idOrKey: string): Promise<Issue>;
+
+  /**
+   * List issues matching the query
+   */
+  listIssues(query?: IssueQuery): Promise<Issue[]>;
+
+  /**
+   * Create a new issue
+   */
+  createIssue(data: CreateIssueData): Promise<Issue>;
+
+  /**
+   * Update an existing issue
+   */
+  updateIssue(idOrKey: string, data: UpdateIssueData): Promise<Issue>;
+
+  /**
+   * Transition an issue to a new status
+   */
+  transitionIssue(idOrKey: string, status: IssueStatus): Promise<Issue>;
+
+  /**
+   * Add a comment to an issue
+   */
+  addComment(idOrKey: string, comment: string): Promise<void>;
+
+  /**
+   * Get available transitions/statuses for an issue
+   */
+  getTransitions?(idOrKey: string): Promise<IssueStatus[]>;
+
+  /**
+   * Assign an issue to a user
+   */
+  assignIssue?(idOrKey: string, assignee: string): Promise<Issue>;
+
+  /**
+   * Link two issues together
+   */
+  linkIssues?(sourceKey: string, targetKey: string, linkType: string): Promise<void>;
+}
+
+/**
+ * Git Provider Adapter
+ *
+ * For integrating with Git hosting services like GitHub, GitLab, Bitbucket, etc.
+ */
+export interface GitProviderAdapter extends BaseAdapter {
+  /**
+   * Get a pull request by ID or number
+   */
+  getPullRequest(idOrNumber: string | number): Promise<PullRequest>;
+
+  /**
+   * List pull requests matching the query
+   */
+  listPullRequests(query?: PullRequestQuery): Promise<PullRequest[]>;
+
+  /**
+   * Create a new pull request
+   */
+  createPullRequest(data: CreatePullRequestData): Promise<PullRequest>;
+
+  /**
+   * Update a pull request
+   */
+  updatePullRequest?(
+    idOrNumber: string | number,
+    data: Partial<CreatePullRequestData>
+  ): Promise<PullRequest>;
+
+  /**
+   * Merge a pull request
+   */
+  mergePullRequest(
+    idOrNumber: string | number,
+    options?: { method?: 'merge' | 'squash' | 'rebase'; message?: string }
+  ): Promise<void>;
+
+  /**
+   * Close a pull request without merging
+   */
+  closePullRequest(idOrNumber: string | number): Promise<void>;
+
+  /**
+   * Add a review to a pull request
+   */
+  addReview(idOrNumber: string | number, review: CreateReviewData): Promise<Review>;
+
+  /**
+   * Get reviews for a pull request
+   */
+  getReviews?(idOrNumber: string | number): Promise<Review[]>;
+
+  /**
+   * Request reviewers for a pull request
+   */
+  requestReviewers?(idOrNumber: string | number, reviewers: string[]): Promise<void>;
+
+  /**
+   * Add a comment to a pull request
+   */
+  addPullRequestComment?(idOrNumber: string | number, comment: string): Promise<void>;
+
+  /**
+   * Get the diff for a pull request
+   */
+  getPullRequestDiff?(idOrNumber: string | number): Promise<string>;
+
+  /**
+   * Get files changed in a pull request
+   */
+  getPullRequestFiles?(idOrNumber: string | number): Promise<string[]>;
+}
+
+/**
+ * Documentation Provider Adapter
+ *
+ * For integrating with documentation systems like Confluence, Notion, GitHub Wiki, etc.
+ */
+export interface DocumentationProviderAdapter extends BaseAdapter {
+  /**
+   * Get a documentation page by ID
+   */
+  getPage(id: string): Promise<DocumentationPage>;
+
+  /**
+   * Get page content (may be separate from metadata in some systems)
+   */
+  getPageContent(id: string): Promise<string>;
+
+  /**
+   * Search for documentation pages
+   */
+  searchPages(query: DocumentationQuery): Promise<DocumentationPage[]>;
+
+  /**
+   * List pages in a space or parent
+   */
+  listPages?(parentId?: string): Promise<DocumentationPage[]>;
+
+  /**
+   * Create a new page
+   */
+  createPage?(title: string, content: string, parentId?: string): Promise<DocumentationPage>;
+
+  /**
+   * Update an existing page
+   */
+  updatePage?(id: string, title?: string, content?: string): Promise<DocumentationPage>;
+}
+
+/**
+ * State Provider Adapter
+ *
+ * For managing local state like KnowledgeLibrary, which may be stored
+ * on the filesystem, in a cloud bucket, or in a documentation system.
+ */
+export interface StateProviderAdapter extends BaseAdapter {
+  /**
+   * Read content from a path
+   */
+  read(path: string, options?: StateOptions): Promise<string>;
+
+  /**
+   * Write content to a path
+   */
+  write(path: string, content: string, options?: StateOptions): Promise<void>;
+
+  /**
+   * Check if a path exists
+   */
+  exists(path: string): Promise<boolean>;
+
+  /**
+   * List entries in a directory
+   */
+  list(path: string): Promise<StateEntry[]>;
+
+  /**
+   * Delete a file or directory
+   */
+  delete(path: string, options?: StateOptions): Promise<void>;
+
+  /**
+   * Create a directory
+   */
+  mkdir?(path: string, options?: StateOptions): Promise<void>;
+
+  /**
+   * Move/rename a file or directory
+   */
+  move?(source: string, destination: string): Promise<void>;
+
+  /**
+   * Copy a file or directory
+   */
+  copy?(source: string, destination: string): Promise<void>;
+}
+
+/**
+ * Union type of all adapter types
+ */
+export type Adapter =
+  | IssueTrackerAdapter
+  | GitProviderAdapter
+  | DocumentationProviderAdapter
+  | StateProviderAdapter;

package/src/adapters/mcp/client.test.ts

@@ -0,0 +1,130 @@
+import { McpClient, createMockMcpClient } from './client.js';
+import { McpError } from './types.js';
+import type { McpTool, McpResource } from './types.js';
+
+describe('MCP Client', () => {
+  describe('McpClient', () => {
+    it('should create client with server name and config', () => {
+      const client = new McpClient('test-server', {
+        transport: 'stdio',
+        command: 'node',
+        args: ['server.js'],
+      });
+
+      expect(client).toBeInstanceOf(McpClient);
+    });
+
+    it('should not be connected initially', () => {
+      const client = new McpClient('test', { transport: 'stdio', command: 'test' });
+      expect(client.isConnected()).toBe(false);
+    });
+
+    it('should return null for server info when not connected', () => {
+      const client = new McpClient('test', { transport: 'stdio', command: 'test' });
+      expect(client.getServerInfo()).toBeNull();
+    });
+
+    it('should throw when calling methods without connection', async () => {
+      const client = new McpClient('test', { transport: 'stdio', command: 'test' });
+
+      await expect(client.listTools()).rejects.toThrow(McpError);
+      await expect(client.listResources()).rejects.toThrow(McpError);
+      await expect(client.callTool('test')).rejects.toThrow(McpError);
+      await expect(client.readResource('test://uri')).rejects.toThrow(McpError);
+    });
+
+    it('should throw for unsupported transport', async () => {
+      const client = new McpClient('test', { transport: 'http', url: 'http://example.com' });
+
+      await expect(client.connect()).rejects.toThrow(McpError);
+      await expect(client.connect()).rejects.toThrow('Unsupported transport type');
+    });
+  });
+
+  describe('createMockMcpClient', () => {
+    it('should create a mock client', () => {
+      const client = createMockMcpClient('mock-server');
+      expect(client).toBeInstanceOf(McpClient);
+    });
+
+    it('should connect successfully', async () => {
+      const client = createMockMcpClient('mock-server');
+      await client.connect();
+
+      expect(client.isConnected()).toBe(true);
+    });
+
+    it('should return server info after connecting', async () => {
+      const client = createMockMcpClient('mock-server');
+      await client.connect();
+
+      const info = client.getServerInfo();
+      expect(info).not.toBeNull();
+      expect(info?.name).toBe('mock-server');
+      expect(info?.version).toBe('1.0.0');
+      expect(info?.connected).toBe(true);
+    });
+
+    it('should return provided tools', async () => {
+      const mockTools: McpTool[] = [
+        { name: 'tool1', inputSchema: { type: 'object' } },
+        { name: 'tool2', inputSchema: { type: 'object' }, description: 'A tool' },
+      ];
+
+      const client = createMockMcpClient('mock-server', mockTools);
+      await client.connect();
+
+      const tools = await client.listTools();
+      expect(tools).toHaveLength(2);
+      expect(tools[0].name).toBe('tool1');
+      expect(tools[1].name).toBe('tool2');
+      expect(tools[1].description).toBe('A tool');
+    });
+
+    it('should return provided resources', async () => {
+      const mockResources: McpResource[] = [
+        { uri: 'file://test.txt', name: 'Test File' },
+        { uri: 'db://records', name: 'Records', description: 'Database records' },
+      ];
+
+      const client = createMockMcpClient('mock-server', [], mockResources);
+      await client.connect();
+
+      const resources = await client.listResources();
+      expect(resources).toHaveLength(2);
+      expect(resources[0].uri).toBe('file://test.txt');
+      expect(resources[1].name).toBe('Records');
+    });
+
+    it('should return empty arrays by default', async () => {
+      const client = createMockMcpClient('mock-server');
+      await client.connect();
+
+      const tools = await client.listTools();
+      const resources = await client.listResources();
+
+      expect(tools).toHaveLength(0);
+      expect(resources).toHaveLength(0);
+    });
+  });
+
+  describe('McpError', () => {
+    it('should create error with message and code', () => {
+      const error = new McpError('Connection failed', 'connection_failed');
+      expect(error.message).toBe('Connection failed');
+      expect(error.code).toBe('connection_failed');
+      expect(error.name).toBe('McpError');
+    });
+
+    it('should include server name', () => {
+      const error = new McpError('Error', 'protocol_error', 'github');
+      expect(error.server).toBe('github');
+    });
+
+    it('should include cause', () => {
+      const cause = new Error('Original error');
+      const error = new McpError('Wrapped', 'network_error', undefined, cause);
+      expect(error.cause).toBe(cause);
+    });
+  });
+});