@elliotding/ai-agent-mcp 0.1.0

package/src/filesystem/manager.ts

@@ -0,0 +1,235 @@
+/**
+ * Filesystem Manager
+ * Atomic filesystem operations for resource management
+ */
+
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as path from 'path';
+import { logger } from '../utils/logger';
+import { createFileSystemError, createValidationError } from '../types/errors';
+
+class FilesystemManager {
+  /**
+   * Write resource file atomically
+   */
+  async writeResource(filePath: string, content: string): Promise<void> {
+    const tempPath = `${filePath}.tmp`;
+
+    try {
+      // Ensure directory exists
+      const dir = path.dirname(filePath);
+      await fs.mkdir(dir, { recursive: true });
+
+      // Write to temporary file
+      await fs.writeFile(tempPath, content, 'utf-8');
+
+      // Validate content (basic check)
+      await this.validateResourceContent(tempPath, content);
+
+      // Atomic rename
+      await fs.rename(tempPath, filePath);
+
+      logger.debug({ filePath }, 'Resource file written successfully');
+    } catch (error) {
+      // Cleanup temporary file
+      try {
+        await fs.unlink(tempPath);
+      } catch {
+        // Ignore cleanup errors
+      }
+
+      throw createFileSystemError('write', filePath, error as Error & { code?: string });
+    }
+  }
+
+  /**
+   * Read resource file with validation
+   */
+  async readResource(filePath: string): Promise<string> {
+    try {
+      // Check if file exists
+      await fs.access(filePath, fsSync.constants.R_OK);
+
+      // Read file
+      const content = await fs.readFile(filePath, 'utf-8');
+
+      // Validate format
+      await this.validateResourceContent(filePath, content);
+
+      return content;
+    } catch (error) {
+      throw createFileSystemError('read', filePath, error as Error & { code?: string });
+    }
+  }
+
+  /**
+   * Delete resource file with backup
+   */
+  async deleteResource(filePath: string): Promise<void> {
+    const backupPath = `${filePath}.backup`;
+
+    try {
+      // Create backup
+      if (fsSync.existsSync(filePath)) {
+        await fs.copyFile(filePath, backupPath);
+      }
+
+      // Delete file
+      await fs.unlink(filePath);
+
+      // Remove backup on success
+      try {
+        await fs.unlink(backupPath);
+      } catch {
+        // Ignore backup cleanup errors
+      }
+
+      logger.debug({ filePath }, 'Resource file deleted successfully');
+    } catch (error) {
+      // Restore from backup on failure
+      try {
+        if (fsSync.existsSync(backupPath)) {
+          await fs.copyFile(backupPath, filePath);
+          await fs.unlink(backupPath);
+        }
+      } catch {
+        // Ignore restore errors
+      }
+
+      throw createFileSystemError('delete', filePath, error as Error & { code?: string });
+    }
+  }
+
+  /**
+   * Validate resource content
+   */
+  private async validateResourceContent(filePath: string, content: string): Promise<void> {
+    const ext = path.extname(filePath);
+
+    // Check if empty
+    if (!content || content.trim().length === 0) {
+      throw createValidationError(filePath, ext, 'File content is empty');
+    }
+
+    // Validate based on file type
+    if (ext === '.json') {
+      try {
+        JSON.parse(content);
+      } catch (error) {
+        throw createValidationError(filePath, 'json', 'Invalid JSON format');
+      }
+    } else if (ext === '.md') {
+      // Basic markdown validation (check for minimum content)
+      if (content.length < 10) {
+        throw createValidationError(filePath, 'markdown', 'Markdown content too short');
+      }
+    }
+  }
+
+  /**
+   * Check if file exists
+   */
+  async fileExists(filePath: string): Promise<boolean> {
+    try {
+      await fs.access(filePath, fsSync.constants.F_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * List files in directory
+   */
+  async listFiles(dirPath: string, pattern?: RegExp): Promise<string[]> {
+    try {
+      const files = await fs.readdir(dirPath, { recursive: true });
+      
+      if (pattern) {
+        return files.filter((file) => pattern.test(file));
+      }
+      
+      return files;
+    } catch (error) {
+      throw createFileSystemError('list', dirPath, error as Error & { code?: string });
+    }
+  }
+
+  /**
+   * Recursively scan a directory and return all text files as FileEntry[]
+   * Supported extensions: .md, .mdc, .txt, .yaml, .yml, .json
+   */
+  async scanDirectory(dirPath: string): Promise<Array<{ path: string; content: string }>> {
+    const TEXT_EXTENSIONS = new Set(['.md', '.mdc', '.txt', '.yaml', '.yml', '.json']);
+    const results: Array<{ path: string; content: string }> = [];
+
+    const walk = async (currentPath: string, relBase: string): Promise<void> => {
+      let entries: fsSync.Dirent[];
+      try {
+        entries = await fs.readdir(currentPath, { withFileTypes: true });
+      } catch (error) {
+        throw createFileSystemError('list', currentPath, error as Error & { code?: string });
+      }
+
+      for (const entry of entries) {
+        const fullPath = path.join(currentPath, entry.name);
+        const relPath = path.join(relBase, entry.name);
+
+        if (entry.isDirectory()) {
+          await walk(fullPath, relPath);
+        } else if (entry.isFile()) {
+          const ext = path.extname(entry.name).toLowerCase();
+          if (TEXT_EXTENSIONS.has(ext)) {
+            try {
+              const content = await fs.readFile(fullPath, 'utf-8');
+              if (content.trim().length > 0) {
+                results.push({ path: relPath, content });
+              }
+            } catch {
+              // Skip unreadable files silently
+              logger.warn({ filePath: fullPath }, 'Skipped unreadable file during directory scan');
+            }
+          }
+        }
+      }
+    };
+
+    await walk(dirPath, '');
+
+    if (results.length === 0) {
+      throw createValidationError(
+        dirPath,
+        'directory',
+        `No text files found in directory: ${dirPath}`
+      );
+    }
+
+    logger.debug({ dirPath, fileCount: results.length }, 'Directory scan completed');
+    return results;
+  }
+
+  /**
+   * Remove empty directories recursively
+   */
+  async removeEmptyDirs(dirPath: string): Promise<void> {
+    try {
+      const files = await fs.readdir(dirPath);
+
+      if (files.length === 0) {
+        await fs.rmdir(dirPath);
+        logger.debug({ dirPath }, 'Empty directory removed');
+
+        // Check parent directory
+        const parentDir = path.dirname(dirPath);
+        if (parentDir !== dirPath) {
+          await this.removeEmptyDirs(parentDir);
+        }
+      }
+    } catch (error) {
+      // Ignore errors (directory might not be empty or already deleted)
+    }
+  }
+}
+
+export const filesystemManager = new FilesystemManager();

package/src/git/multi-source-manager.ts

@@ -0,0 +1,333 @@
+/**
+ * Multi-Source Git Manager
+ * Manages multiple AI Resources Git repositories efficiently
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import simpleGit from 'simple-git';
+import { logger } from '../utils/logger';
+import { createGitError } from '../types/errors';
+
+interface AIResourcesConfig {
+  version: string;
+  default_source: SourceConfig;
+  extended_sources: SourceConfig[];
+}
+
+interface SourceConfig {
+  name: string;
+  path: string;
+  enabled: boolean;
+  priority: number;
+  git_url?: string;  // Git repository URL
+  git_branch?: string;  // Git branch (default: main)
+  resources: {
+    commands: string;
+    skills: string;
+    mcp: string;
+    rules: string;
+  };
+  description: string;
+}
+
+interface SyncResult {
+  source: string;
+  action: 'cloned' | 'pulled' | 'up-to-date' | 'skipped';
+  changes: number;
+  duration: number;
+}
+
+class MultiSourceGitManager {
+  private configPath: string;
+  private baseDir: string;
+
+  constructor(baseDir: string) {
+    this.baseDir = baseDir;
+    this.configPath = path.join(baseDir, 'ai-resources-config.json');
+  }
+
+  /**
+   * Load AI Resources configuration
+   */
+  private async loadConfig(): Promise<AIResourcesConfig> {
+    try {
+      const configContent = await fs.readFile(this.configPath, 'utf-8');
+      return JSON.parse(configContent);
+    } catch (error) {
+      throw new Error(`Failed to load AI Resources config: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Get all enabled sources (including default)
+   */
+  private async getEnabledSources(): Promise<SourceConfig[]> {
+    const config = await this.loadConfig();
+    const sources: SourceConfig[] = [];
+
+    if (config.default_source.enabled) {
+      sources.push(config.default_source);
+    }
+
+    if (config.extended_sources) {
+      sources.push(...config.extended_sources.filter(s => s.enabled));
+    }
+
+    return sources;
+  }
+
+  /**
+   * Check if a Git repository exists at the given path
+   */
+  private async repositoryExists(repoPath: string): Promise<boolean> {
+    try {
+      const gitDir = path.join(repoPath, '.git');
+      const stats = await fs.stat(gitDir);
+      return stats.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get Git repository URL from existing repo
+   */
+  private async getRepoUrl(repoPath: string): Promise<string | null> {
+    try {
+      const git = simpleGit(repoPath);
+      const remotes = await git.getRemotes(true);
+      const origin = remotes.find(r => r.name === 'origin');
+      return origin?.refs.fetch || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Clone a Git repository
+   */
+  private async cloneRepository(repoUrl: string, targetPath: string, branch: string = 'main'): Promise<void> {
+    try {
+      logger.info({ repoUrl, targetPath, branch }, 'Cloning Git repository...');
+      
+      // Ensure parent directory exists
+      const parentDir = path.dirname(targetPath);
+      await fs.mkdir(parentDir, { recursive: true });
+
+      const git = simpleGit();
+
+      // Clone with --single-branch to limit downloaded history to the target
+      // branch only, keeping the clone fast without creating a shallow repo
+      // (shallow repos cause "no merge base" errors on subsequent fetches).
+      await git.clone(repoUrl, targetPath, [
+        '--branch', branch,
+        '--single-branch',
+      ]);
+
+      logger.info({ repoUrl, targetPath }, 'Repository cloned successfully');
+    } catch (error) {
+      throw createGitError('clone', error as Error, repoUrl);
+    }
+  }
+
+  /**
+   * Pull latest changes using fetch + fast-forward merge.
+   *
+   * Deliberately avoids --depth=1 on fetch: shallow fetches truncate local
+   * history, causing "no merge base" divergence errors on subsequent pulls.
+   */
+  private async pullRepository(repoPath: string, branch: string = 'main'): Promise<{
+    hasChanges: boolean;
+    filesChanged: number;
+  }> {
+    try {
+      const git = simpleGit(repoPath);
+
+      logger.info({ repoPath, branch }, 'Fetching latest changes...');
+
+      // If the local repo is shallow (was previously cloned with --depth),
+      // unshallow it first so subsequent fetches have a proper merge base.
+      const isShallow = (await git.raw(['rev-parse', '--is-shallow-repository'])).trim() === 'true';
+      if (isShallow) {
+        logger.info({ repoPath }, 'Shallow repo detected — running fetch --unshallow first');
+        await git.fetch(['--unshallow', 'origin', branch]);
+      } else {
+        // Fetch the branch from origin without --depth to keep full history intact.
+        await git.fetch(['origin', branch]);
+      }
+
+      // Compare local HEAD with remote tip to detect changes before merging.
+      const remoteBranch = `origin/${branch}`;
+      const diffSummary = await git.diffSummary([`HEAD...${remoteBranch}`]);
+      const hasChanges = diffSummary.files.length > 0;
+
+      if (!hasChanges) {
+        logger.info({ repoPath }, 'Repository is up-to-date, no changes to pull');
+        return { hasChanges: false, filesChanged: 0 };
+      }
+
+      // Fast-forward only — never auto-merge diverged histories.
+      logger.info({ repoPath, filesChanged: diffSummary.files.length }, 'Pulling changes...');
+      await git.merge([remoteBranch, '--ff-only']);
+
+      logger.info({
+        repoPath,
+        filesChanged: diffSummary.files.length,
+        insertions: diffSummary.insertions,
+        deletions: diffSummary.deletions,
+      }, 'Repository updated successfully');
+
+      return { hasChanges: true, filesChanged: diffSummary.files.length };
+    } catch (error) {
+      throw createGitError('pull', error as Error, repoPath);
+    }
+  }
+
+  /**
+   * Sync a single source repository
+   */
+  private async syncSource(source: SourceConfig): Promise<SyncResult> {
+    const startTime = Date.now();
+    const sourcePath = path.join(this.baseDir, source.path);
+
+    logger.info({ 
+      source: source.name, 
+      path: sourcePath,
+      priority: source.priority
+    }, 'Syncing AI Resources source...');
+
+    try {
+      const exists = await this.repositoryExists(sourcePath);
+
+      if (!exists) {
+        // First time: clone repository
+        if (!source.git_url) {
+          logger.warn({ source: source.name }, 'Source has no git_url configured, skipping clone');
+          return {
+            source: source.name,
+            action: 'skipped',
+            changes: 0,
+            duration: Date.now() - startTime
+          };
+        }
+
+        logger.info({ source: source.name }, 'Repository does not exist, cloning...');
+        await this.cloneRepository(
+          source.git_url,
+          sourcePath,
+          source.git_branch || 'main'
+        );
+
+        return {
+          source: source.name,
+          action: 'cloned',
+          changes: -1,  // -1 means full clone
+          duration: Date.now() - startTime
+        };
+      } else {
+        // Repository exists: pull latest changes
+        logger.info({ source: source.name }, 'Repository exists, pulling latest changes...');
+        
+        const { hasChanges, filesChanged } = await this.pullRepository(
+          sourcePath,
+          source.git_branch || 'main'
+        );
+
+        return {
+          source: source.name,
+          action: hasChanges ? 'pulled' : 'up-to-date',
+          changes: filesChanged,
+          duration: Date.now() - startTime
+        };
+      }
+    } catch (error) {
+      logger.error({ 
+        source: source.name,
+        error: error instanceof Error ? error.message : String(error)
+      }, 'Failed to sync source');
+      
+      throw error;
+    }
+  }
+
+  /**
+   * Sync all enabled sources
+   */
+  async syncAllSources(): Promise<SyncResult[]> {
+    logger.info('Starting multi-source sync...');
+    
+    const sources = await this.getEnabledSources();
+    logger.info({ 
+      totalSources: sources.length,
+      sourceNames: sources.map(s => s.name)
+    }, 'Found enabled sources');
+
+    const results: SyncResult[] = [];
+
+    for (const source of sources) {
+      try {
+        const result = await this.syncSource(source);
+        results.push(result);
+      } catch (error) {
+        logger.error({ 
+          source: source.name,
+          error: error instanceof Error ? error.message : String(error)
+        }, 'Failed to sync source, continuing with next...');
+        
+        results.push({
+          source: source.name,
+          action: 'skipped',
+          changes: 0,
+          duration: 0
+        });
+      }
+    }
+
+    logger.info({ 
+      results,
+      totalSources: results.length,
+      cloned: results.filter(r => r.action === 'cloned').length,
+      pulled: results.filter(r => r.action === 'pulled').length,
+      upToDate: results.filter(r => r.action === 'up-to-date').length
+    }, 'Multi-source sync completed');
+
+    return results;
+  }
+
+  /**
+   * Check status of all sources without pulling
+   */
+  async checkAllSources(): Promise<Array<{
+    source: string;
+    exists: boolean;
+    hasRemote: boolean;
+    repoUrl: string | null;
+  }>> {
+    const sources = await this.getEnabledSources();
+    const statuses = [];
+
+    for (const source of sources) {
+      const sourcePath = path.join(this.baseDir, source.path);
+      const exists = await this.repositoryExists(sourcePath);
+      
+      let repoUrl = null;
+      if (exists) {
+        repoUrl = await this.getRepoUrl(sourcePath);
+      }
+
+      statuses.push({
+        source: source.name,
+        exists,
+        hasRemote: !!repoUrl,
+        repoUrl
+      });
+    }
+
+    return statuses;
+  }
+}
+
+// Export singleton instance
+const AI_RESOURCES_BASE = path.resolve(process.cwd(), '../AI-Resources');
+export const multiSourceGitManager = new MultiSourceGitManager(AI_RESOURCES_BASE);

package/src/git/operations.ts

@@ -0,0 +1,93 @@
+/**
+ * Git Operations Module
+ * Per-repo git helpers used by upload_resource to target a specific source repo.
+ * All repo URLs and branches come from AI-Resources/ai-resources-config.json —
+ * not from environment variables.
+ */
+
+import simpleGit from 'simple-git';
+import { config } from '../config';
+import { logger } from '../utils/logger';
+import { createGitError } from '../types/errors';
+
+class GitOperations {
+  // ---- Per-repo helpers (used by upload_resource to target a specific source) ----
+
+  /**
+   * Check whether a git repository exists at an arbitrary local path
+   */
+  async repositoryExistsAt(repoPath: string): Promise<boolean> {
+    try {
+      const git = simpleGit({ baseDir: repoPath, binary: 'git', maxConcurrentProcesses: 6 });
+      await git.status();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get current branch of an arbitrary local repo
+   */
+  async getCurrentBranchAt(repoPath: string): Promise<string> {
+    try {
+      const git = simpleGit({ baseDir: repoPath, binary: 'git', maxConcurrentProcesses: 6 });
+      const branchSummary = await git.branch();
+      return branchSummary.current;
+    } catch (error) {
+      throw createGitError('get-branch', error as Error);
+    }
+  }
+
+  /**
+   * Commit and push to a specific repo / remote url / branch.
+   * Creates a unique remote testing branch and returns a PR URL.
+   */
+  async commitAndPushRepo(
+    repoPath: string,
+    remoteUrl: string,
+    baseBranch: string,
+    message: string,
+    files?: string[]
+  ): Promise<{ commitHash: string; prUrl?: string }> {
+    try {
+      const git = simpleGit({ baseDir: repoPath, binary: 'git', maxConcurrentProcesses: 6 });
+
+      logger.info({ repoPath, remoteUrl, message, fileCount: files?.length }, 'Committing and pushing to source repo...');
+
+      await git.addConfig('user.name', config.git.userName);
+      await git.addConfig('user.email', config.git.userEmail);
+
+      const branchSummary = await git.branch();
+      const currentBranch = branchSummary.current;
+
+      const timestamp = Date.now();
+      const randomSuffix = Math.random().toString(36).substring(2, 8);
+      const remoteBranchName = `dev-${currentBranch}-testing-${timestamp}-${randomSuffix}`;
+      logger.info({ remoteBranchName }, 'Generated remote branch name for PR');
+
+      if (files && files.length > 0) {
+        await git.add(files);
+      } else {
+        await git.add('.');
+      }
+
+      const commitResult = await git.commit(message);
+      const commitHash = commitResult.commit;
+      logger.info({ commitHash }, 'Git commit created');
+
+      await git.push(remoteUrl, `${currentBranch}:${remoteBranchName}`);
+      logger.info({ remoteBranchName }, 'Git push completed');
+
+      const repoBaseUrl = remoteUrl.replace(/\.git$/, '');
+      const prUrl = `${repoBaseUrl}/compare/${baseBranch}...${remoteBranchName}`;
+      logger.info({ prUrl, commitHash }, 'PR URL generated');
+
+      return { commitHash, prUrl };
+    } catch (error) {
+      throw createGitError('commit-push', error as Error, remoteUrl);
+    }
+  }
+}
+
+export const gitOperations = new GitOperations();