imcp 0.0.14 → 0.0.16

package/src/core/onboard/FeedOnboardService.ts

@@ -0,0 +1,346 @@
+import { FeedConfiguration, McpConfig } from '../types.js';
+import { configProvider, ConfigurationProvider } from '../ConfigurationProvider.js';
+import { feedValidator } from '../validators/FeedValidator.js';
+import { Logger } from '../../utils/logger.js';
+import { OnboardStatus, OnboardingProcessStatus, OperationStatus, OperationType, ValidationOperationResult } from './OnboardStatus.js';
+import { onboardStatusManager } from './OnboardStatusManager.js';
+import { onboardProcessor } from './OnboardProcessor.js';
+
+const NON_COMPLETED_ONBOARDING_STATUSES: OnboardingProcessStatus[] = [
+  OnboardingProcessStatus.PENDING,
+  OnboardingProcessStatus.VALIDATING,
+  OnboardingProcessStatus.VALIDATED,
+  OnboardingProcessStatus.PR_CREATING,
+];
+
+/**
+ * Service for handling feed onboarding operations
+ */
+export class FeedOnboardService {
+  // tempDir and repoDir will be generated per onboarding process
+
+  constructor() {
+    // No shared tempDir or repoDir at instance level
+  }
+
+  /**
+   * Onboard a new feed configuration
+   * @param config Feed configuration to onboard
+   */
+  public async onboardFeed(config: FeedConfiguration, forExistingCategory?: boolean): Promise<OperationStatus & { feedConfiguration?: FeedConfiguration }> {
+    // Perform static validation first
+    await this.validateStaticConfig(config, forExistingCategory);
+
+    const operationStatus = await this._initiateOperation(config, 'FULL_ONBOARDING', forExistingCategory);
+
+    return { ...operationStatus, feedConfiguration: config };
+  }
+
+  /**
+   * Validate a feed configuration without performing full onboarding
+   * @param config Feed configuration to validate
+   * @returns Operation status indicating the result of the validation initiation
+   */
+  public async validateFeed(config: FeedConfiguration, forExistingCategory?: boolean): Promise<OperationStatus & { feedConfiguration?: FeedConfiguration }> {
+    // Perform static validation first
+    await this.validateStaticConfig(config, forExistingCategory);
+
+    const operationStatus = await this._initiateOperation(config, 'VALIDATION_ONLY', forExistingCategory);
+
+    return { ...operationStatus, feedConfiguration: config };
+  }
+
+  /**
+   * Initiates either a full onboarding or a validation-only operation.
+   * It checks for existing non-completed operations for the same feed and operation type.
+   * If an existing operation is found, its status is returned. Otherwise, a new operation is created and started.
+   * @param config The feed configuration.
+   * @param operationType The type of operation to initiate (FULL_ONBOARDING or VALIDATION_ONLY).
+   * @returns A promise that resolves to the operation status.
+   */
+  private async _initiateOperation(config: FeedConfiguration, operationType: OperationType, forExistingCategory?: boolean): Promise<OperationStatus> {
+    let existingOperation = await this._findExistingNonCompletedOperation(config.name, operationType);
+
+    if (existingOperation) {
+      // OnboardStatus has a lastUpdated field (ISO string)
+      // This field is updated by OnboardStatusManager.updateStatus
+      const fiveMinutesInMs = 5 * 60 * 1000;
+      const lastUpdateTimestamp = existingOperation.lastUpdated ? new Date(existingOperation.lastUpdated).getTime() : 0;
+      const currentTime = new Date().getTime();
+
+      if (lastUpdateTimestamp > 0 && (currentTime - lastUpdateTimestamp) > fiveMinutesInMs) {
+        Logger.log(`WARNING: [${existingOperation.onboardingId}] Found stale ${operationType} operation for feed: ${config.name} (last updated at: ${existingOperation.lastUpdated}). Proceeding to create a new operation.`);
+
+        existingOperation = undefined; // Treat as no existing operation for starting a new one
+      } else {
+        Logger.log(`[${existingOperation.onboardingId}] Found existing non-completed ${operationType} operation for feed: ${config.name}. Returning its status.`);
+        return {
+          onboardingId: existingOperation.onboardingId,
+          status: existingOperation.status,
+          message: `An ${operationType} process for this feed (${existingOperation.onboardingId}) is already in status: ${existingOperation.status}. Current step: ${existingOperation.currentStep || 'N/A'}`,
+          lastQueried: new Date().toISOString(),
+        };
+      }
+    }
+
+    // serverName is removed
+    const initialStatus = await onboardStatusManager.createInitialStatus(config.name, operationType);
+    const onboardingId = initialStatus.onboardingId;
+
+    await onboardStatusManager.saveFeedConfiguration(onboardingId, config);
+
+    if (operationType === 'FULL_ONBOARDING') {
+      this.processFullOnboarding(onboardingId, config).catch(async (error) => {
+        Logger.error(`[${onboardingId}] Full feed onboarding process failed:`, error);
+        await onboardStatusManager.updateStatus(onboardingId, {
+          status: OnboardingProcessStatus.FAILED,
+          errorMessage: error instanceof Error ? error.message : String(error),
+          currentStep: 'Failed during full onboarding process',
+          prInfo: undefined,
+        });
+      });
+    } else if (operationType === 'VALIDATION_ONLY') {
+      this.processValidationOnly(onboardingId, config).catch(async (error) => {
+        Logger.error(`[${onboardingId}] Feed validation process failed:`, error);
+        await onboardStatusManager.updateStatus(onboardingId, {
+          status: OnboardingProcessStatus.FAILED,
+          errorMessage: error instanceof Error ? error.message : String(error),
+          currentStep: 'Failed during validation process',
+          validationStatus: (error as any).validationStatus || { isValid: false, message: error instanceof Error ? error.message : String(error) },
+          prInfo: undefined,
+        });
+      });
+    }
+
+    return {
+      onboardingId,
+      status: OnboardingProcessStatus.PENDING,
+      message: `New ${operationType} process started with ID: ${onboardingId}.`,
+      lastQueried: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Finds an existing non-completed operation for a given feed name, server name, and operation type.
+   * @param feedName The name of the feed.
+   * @param operationType The type of operation.
+   * @returns A promise that resolves to the OnboardStatus of the existing operation, or undefined if not found.
+   */
+  private async _findExistingNonCompletedOperation(
+    feedName: string,
+    operationType: OperationType
+  ): Promise<OnboardStatus | undefined> {
+    const allStatuses = await onboardStatusManager.getAllStatuses();
+    return Object.values(allStatuses).find(
+      (status) =>
+        status.feedName === feedName &&
+        // status.serverName === serverName && // serverName is removed
+        status.operationType === operationType &&
+        NON_COMPLETED_ONBOARDING_STATUSES.includes(status.status)
+    );
+  }
+
+  /**
+   * Performs static validation of the feed configuration.
+   * @param config The feed configuration to validate.
+   * @param forExistingCategory Whether this is for an existing category.
+   * @throws Error if validation fails.
+   */
+  private async validateStaticConfig(config: FeedConfiguration, forExistingCategory?: boolean): Promise<void> {
+    // --- Start of moved and enhanced static validation ---
+    if (!config || typeof config !== 'object') { // Check if config itself is a valid object
+      throw new Error('Invalid configuration: Input must be a valid object.');
+    }
+    if (typeof config.name !== 'string' || !config.name.trim()) {
+      throw new Error('Invalid configuration: "name" must be a non-empty string.');
+    }
+    if (!Array.isArray(config.requirements)) {
+      throw new Error('Invalid configuration: "requirements" must be an array.');
+    }
+    if (!Array.isArray(config.mcpServers)) {
+      throw new Error('Invalid configuration: "mcpServers" must be an array.');
+    }
+    // --- End of moved static validation ---
+
+    const existingConfig = await configProvider.getFeedConfiguration(config.name);
+
+    if (forExistingCategory) {
+      if (!existingConfig) {
+        throw new Error(`Cannot update non-existent category: ${config.name}. Please ensure the category name is correct or create it as a new category.`);
+      }
+      // Original logic from existing validateStaticConfig:
+      // This implies that for an existing category, the payload must define mcpServers,
+      // and at least one of them must be new.
+      // If config.mcpServers is empty, newServersInPayload.length will be 0, leading to an error.
+      const existingServerNames = new Set(existingConfig.mcpServers.map((s: McpConfig) => s.name));
+      const newServersInPayload = config.mcpServers.filter((s: McpConfig) => !existingServerNames.has(s.name));
+
+      if (newServersInPayload.length === 0) {
+        // This error triggers if config.mcpServers is empty, or if all servers in config.mcpServers already exist.
+        throw new Error('No new servers provided for the existing category. Ensure the "mcpServers" list in your payload contains at least one server not already in this category, or that the list is not empty if you intend to add servers.');
+      }
+    } else { // For new categories
+      if (existingConfig) {
+        throw new Error(`Category "${config.name}" already exists. To modify an existing category, please indicate that it is for an existing category.`);
+      }
+      if (!config.mcpServers || config.mcpServers.length === 0) {
+        throw new Error('Server configuration ("mcpServers") must be provided and non-empty for new categories.');
+      }
+    }
+  }
+
+  /**
+   * Validates the feed configuration.
+   * Updates the onboarding status to VALIDATING, then to VALIDATED or FAILED based on the validation result.
+   * @param onboardingId The ID of the onboarding process.
+   * @param config The feed configuration to validate.
+   * @throws Error if validation fails, to be caught by the calling process.
+   */
+  private async _validateFeedConfiguration(onboardingId: string, config: FeedConfiguration): Promise<void> {
+    await onboardStatusManager.updateStatus(onboardingId, { status: OnboardingProcessStatus.VALIDATING, currentStep: 'Validating feed configuration' });
+    let overallValidationStatus: ValidationOperationResult['validationStatus'] = { isValid: true, serverResults: [] };
+    try {
+      feedValidator.validate(config);
+
+      // Then, validate each MCP server
+      for (const server of config.mcpServers) {
+        try {
+          await feedValidator.validateServer(server, config);
+          overallValidationStatus.serverResults?.push({ serverName: server.name, isValid: true });
+          await onboardStatusManager.updateStatus(onboardingId, {
+            currentStep: `Validated server: ${server.name}`,
+            validationStatus: overallValidationStatus // Update with intermediate results
+          });
+        } catch (serverValidationError: any) {
+          overallValidationStatus.isValid = false;
+          overallValidationStatus.serverResults?.push({
+            serverName: server.name,
+            isValid: false,
+            message: serverValidationError.message || String(serverValidationError)
+          });
+          // Update status immediately upon first server validation failure
+          await onboardStatusManager.updateStatus(onboardingId, {
+            status: OnboardingProcessStatus.FAILED,
+            currentStep: `Validation failed for server: ${server.name}`,
+            errorMessage: `Server ${server.name}: ${serverValidationError.message || String(serverValidationError)}`,
+            validationStatus: overallValidationStatus
+          });
+          throw serverValidationError; // Propagate the error to fail the whole validation
+        }
+      }
+
+      // If all servers validated successfully
+      await onboardStatusManager.updateStatus(onboardingId, {
+        status: OnboardingProcessStatus.VALIDATED,
+        currentStep: 'All servers in feed configuration validated successfully',
+        validationStatus: overallValidationStatus
+      });
+    } catch (error) {
+      const validationError = error as any; // Assuming error might have validation details
+      // This block will now primarily catch errors from the main feedValidator.validate(config)
+      // or if a server validation error was re-thrown and not caught by the loop's catch.
+      await onboardStatusManager.updateStatus(onboardingId, {
+        status: OnboardingProcessStatus.FAILED,
+        currentStep: 'Feed configuration validation failed',
+        errorMessage: validationError.message || String(error),
+        validationStatus: { // Ensure this reflects the actual state, potentially including partial server results
+          isValid: false,
+          message: validationError.message || String(error),
+          serverResults: overallValidationStatus.serverResults // Include any server results gathered so far
+        }
+      });
+      throw error; // Re-throw to be caught by the calling process
+    }
+  }
+
+  /**
+   * Processes a validation-only operation for a feed configuration.
+   * It validates the configuration and updates the status to SUCCEEDED if validation is successful.
+   * If validation fails, the error is handled by _validateFeedConfiguration and the calling _initiateOperation method.
+   * @param onboardingId The ID of the onboarding process.
+   * @param config The feed configuration.
+   */
+  private async processValidationOnly(onboardingId: string, config: FeedConfiguration, forExistingCategory?: boolean): Promise<void> {
+    try {
+      await this._validateFeedConfiguration(onboardingId, config);
+      // _validateFeedConfiguration now handles setting VALIDATED or FAILED.
+      // If it completes without throwing, it means validation was successful.
+      const finalStatus = await onboardStatusManager.getStatus(onboardingId);
+      const result: ValidationOperationResult = {
+        validationStatus: finalStatus?.validationStatus || { isValid: true, serverResults: [] }, // Get the detailed status
+        feedConfiguration: config
+      };
+      await onboardStatusManager.updateStatus(onboardingId, {
+        status: OnboardingProcessStatus.SUCCEEDED, // Mark as SUCCEEDED for VALIDATION_ONLY
+        currentStep: 'Feed configuration validated successfully',
+        errorMessage: undefined,
+        prInfo: undefined,
+        result: result
+      });
+      Logger.log(`[${onboardingId}] Successfully validated feed: ${config.name}`);
+    } catch (error) {
+      // Error handling is done within _validateFeedConfiguration and by the caller of processValidationOnly
+      Logger.error(`[${onboardingId}] Feed validation process failed for ${config.name}:`, error);
+      // No need to re-throw here as the caller's catch block will handle it.
+    }
+  }
+
+
+  /**
+   * Processes the full onboarding for a feed configuration.
+   * This includes validation, forking/cloning the repository, saving the config, and creating a pull request.
+   * Manages status updates throughout the process and handles cleanup of temporary directories.
+   * @param onboardingId The ID of the onboarding process.
+   * @param config The feed configuration.
+   * @throws Error if any step of the full onboarding process fails.
+   */
+  private async processFullOnboarding(onboardingId: string, config: FeedConfiguration, forExistingCategory?: boolean): Promise<void> {
+    const { tempDir, repoDir } = onboardProcessor.createDirectories(onboardingId);
+    try {
+      await this._validateFeedConfiguration(onboardingId, config);
+
+      await onboardStatusManager.updateStatus(onboardingId, { status: OnboardingProcessStatus.PR_CREATING, currentStep: 'Forking repository' });
+      await onboardProcessor.forkRepo(onboardingId, repoDir);
+
+      await onboardStatusManager.updateStatus(onboardingId, { status: OnboardingProcessStatus.PR_CREATING, currentStep: 'Cloning repository' });
+      await onboardProcessor.cloneRepo(onboardingId, tempDir, repoDir);
+
+      await onboardStatusManager.updateStatus(onboardingId, { status: OnboardingProcessStatus.PR_CREATING, currentStep: 'Setting up branch' });
+      const branchName = await onboardProcessor.setupBranch(onboardingId, config, repoDir);
+
+      await onboardStatusManager.updateStatus(onboardingId, { status: OnboardingProcessStatus.PR_CREATING, currentStep: 'Saving feed configuration to repository' });
+      await onboardProcessor.saveFeedConfigToRepo(onboardingId, config, repoDir);
+
+      await onboardStatusManager.updateStatus(onboardingId, { status: OnboardingProcessStatus.PR_CREATING, currentStep: 'Creating pull request' });
+      const prInfo = await onboardProcessor.createPullRequest(onboardingId, config, repoDir, branchName);
+
+      await onboardStatusManager.updateStatus(onboardingId, {
+        status: OnboardingProcessStatus.SUCCEEDED,
+        currentStep: 'Successfully onboarded',
+        errorMessage: undefined,
+        prInfo: prInfo,
+        result: prInfo.url
+      });
+      Logger.log(`[${onboardingId}] Successfully onboarded feed: ${config.name}`);
+    } catch (error) {
+      Logger.error(`[${onboardingId}] Full feed onboarding failed:`, error);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      let currentStep = 'Failed during full onboarding process';
+      if (error instanceof Error && 'step' in error) {
+        currentStep = `Failed at step: ${error.step}`;
+      } else if ((await onboardStatusManager.getStatus(onboardingId))?.currentStep?.includes('validation failed')) {
+        throw error;
+      }
+
+      await onboardStatusManager.updateStatus(onboardingId, {
+        status: OnboardingProcessStatus.FAILED,
+        errorMessage: errorMessage,
+        currentStep: currentStep,
+      });
+      throw error;
+    }
+  }
+}
+
+// Export singleton instance
+export const feedOnboardService = new FeedOnboardService();

package/src/core/onboard/OnboardProcessor.ts

@@ -0,0 +1,305 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import fs from 'fs/promises';
+import path from 'path';
+import { GITHUB_REPO, SETTINGS_DIR } from '../constants.js';
+import { FeedConfiguration } from '../types.js';
+import { Logger } from '../../utils/logger.js';
+
+const execAsync = promisify(exec);
+
+/**
+ * Class responsible for handling GitHub operations during the onboarding process
+ */
+export class OnboardProcessor {
+    /**
+     * Forks the GitHub repository specified in GITHUB_REPO constants.
+     * Uses the `gh repo fork` command.
+     * @param onboardingId The ID of the onboarding process (for logging).
+     * @param repoDir The directory of the repository (currently unused but kept for consistency).
+     * @throws An error if the forking process fails, with a 'step' property set to 'forkRepo'.
+     */
+    public async forkRepo(onboardingId: string, repoDir: string): Promise<void> {
+        try {
+            // Using --remote=true ensures that if the fork already exists, 'origin' remote is set to it.
+            // If the fork doesn't exist, it creates it and sets 'origin' remote.
+            await execAsync(`gh repo fork ${GITHUB_REPO.repoName} --clone=false --remote=true`);
+            Logger.debug(`[${onboardingId}] Successfully ensured repository is forked and remote 'origin' is set.`);
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            Logger.error(`[${onboardingId}] Error during forkRepo: ${errorMessage}`);
+            throw Object.assign(new Error(`Failed to fork repository: ${errorMessage}`), { step: 'forkRepo' });
+        }
+    }
+
+    /**
+     * Clones the user's fork of the repository into a temporary directory.
+     * It first removes any existing repository directory for the current onboarding process.
+     * Then, it retrieves the GitHub username and constructs the repository URL to clone.
+     * @param onboardingId The ID of the onboarding process (for logging).
+     * @param tempDir The base temporary directory for the onboarding process.
+     * @param repoDir The specific directory within tempDir where the repository will be cloned.
+     * @throws An error if cloning fails, with a 'step' property set to 'cloneRepo'.
+     */
+    public async cloneRepo(onboardingId: string, tempDir: string, repoDir: string): Promise<void> {
+        try {
+            await fs.mkdir(tempDir, { recursive: true });
+
+            let repoExistsAndIsValid = false;
+            const originalCwd = process.cwd();
+
+            try {
+                const gitDirStat = await fs.stat(path.join(repoDir, '.git'));
+                if (gitDirStat.isDirectory()) {
+                    process.chdir(repoDir);
+                    const { stdout: remoteUrlStdout } = await execAsync(`git config --get remote.origin.url`);
+                    const remoteUrl = remoteUrlStdout.trim();
+                    process.chdir(originalCwd);
+
+                    const username = await this.getGitHubUsername();
+                    const expectedRepoName = GITHUB_REPO.repoName.split('/')[1];
+
+                    if (remoteUrl.includes(username) && remoteUrl.includes(expectedRepoName)) {
+                        Logger.debug(`[${onboardingId}] Repository directory ${repoDir} already exists, is a valid git repository, and has the correct remote origin. Skipping clone.`);
+                        repoExistsAndIsValid = true;
+                    } else {
+                        Logger.log(`WARNING: [${onboardingId}] Repository directory ${repoDir} exists and is a git repository, but remote 'origin' URL (${remoteUrl}) does not match expected user/repo. Will re-clone.`);
+                    }
+                }
+            } catch (checkError: any) {
+                Logger.debug(`[${onboardingId}] Repository directory ${repoDir} check failed or is not the correct repository. Proceeding with clone. Error: ${checkError.message || checkError.code}`);
+                if (process.cwd() !== originalCwd) {
+                    process.chdir(originalCwd);
+                }
+            }
+
+            if (!repoExistsAndIsValid) {
+                await fs.rm(repoDir, { recursive: true, force: true });
+                Logger.debug(`[${onboardingId}] Cleaned up existing directory (if any) at ${repoDir}.`);
+
+                const username = await this.getGitHubUsername();
+                const repoUrl = `https://github.com/${username}/${GITHUB_REPO.repoName.split('/')[1]}.git`;
+
+                await execAsync(`git clone ${repoUrl} ${repoDir}`);
+                Logger.debug(`[${onboardingId}] Successfully cloned repository to ${repoDir}`);
+            }
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            Logger.error(`[${onboardingId}] Error during cloneRepo: ${errorMessage}`);
+            throw Object.assign(new Error(`Failed to clone repository: ${errorMessage}`), { step: 'cloneRepo' });
+        }
+    }
+
+    /**
+     * Retrieves the GitHub username of the authenticated user using the `gh api user` command.
+     * @returns A promise that resolves to the GitHub username as a string.
+     * @throws An error if fetching the username fails.
+     */
+    private async getGitHubUsername(): Promise<string> {
+        try {
+            const { stdout } = await execAsync('gh api user -q .login');
+            return stdout.trim();
+        } catch (error) {
+            throw new Error(`Failed to get GitHub username: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+
+    /**
+     * Saves the feed configuration as a JSON file into the specified path within the cloned repository.
+     * The file will be named `config.name.json`.
+     * @param onboardingId The ID of the onboarding process.
+     * @param config The feed configuration to save.
+     * @param repoDir The root directory of the cloned repository.
+     * @throws An error if saving the configuration fails, with a 'step' property set to 'saveFeedConfigToRepo'.
+     */
+    public async saveFeedConfigToRepo(onboardingId: string, config: FeedConfiguration, repoDir: string): Promise<void> {
+        try {
+            const feedsDir = path.join(repoDir, GITHUB_REPO.feedsPath);
+            await fs.mkdir(feedsDir, { recursive: true });
+
+            const configPath = path.join(feedsDir, `${config.name}.json`);
+            await fs.writeFile(configPath, JSON.stringify(config, null, 2));
+            Logger.debug(`[${onboardingId}] Saved feed configuration to ${configPath}`);
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            Logger.error(`[${onboardingId}] Error during saveFeedConfigToRepo: ${errorMessage}`);
+            throw Object.assign(new Error(`Failed to save feed configuration to repo: ${errorMessage}`), { step: 'saveFeedConfigToRepo' });
+        }
+    }
+
+    /**
+     * Creates a pull request on GitHub for the newly added feed configuration.
+     * @param onboardingId The ID of the onboarding process.
+     * @param config The feed configuration, used for branch name and PR details.
+     * @param repoDir The root directory of the cloned repository.
+     * @returns A promise that resolves to an object containing the URL of the created PR and the branch name.
+     * @throws An error if any step of the PR creation process fails.
+     */
+    /**
+     * Sets up a clean branch for the feed configuration changes.
+     * @param onboardingId The ID of the onboarding process.
+     * @param config The feed configuration.
+     * @param repoDir The root directory of the cloned repository.
+     * @returns The name of the created branch.
+     * @throws An error if branch setup fails.
+     */
+    public async setupBranch(onboardingId: string, config: FeedConfiguration, repoDir: string): Promise<string> {
+        try {
+            process.chdir(repoDir);
+
+            try {
+                await execAsync(`git remote get-url upstream`);
+                await execAsync(`git remote set-url upstream ${GITHUB_REPO.url}`);
+                Logger.debug(`[${onboardingId}] Updated 'upstream' remote URL to ${GITHUB_REPO.url}`);
+            } catch (remoteError) {
+                await execAsync(`git remote add upstream ${GITHUB_REPO.url}`);
+                Logger.debug(`[${onboardingId}] Added 'upstream' remote with URL ${GITHUB_REPO.url}`);
+            }
+
+            await execAsync('git fetch upstream');
+            Logger.debug(`[${onboardingId}] Fetched from upstream.`);
+
+            try {
+                await execAsync('git checkout main');
+                Logger.debug(`[${onboardingId}] Switched to existing local branch 'main'.`);
+            } catch (checkoutMainError: any) {
+                const errStdErr = checkoutMainError.stderr || '';
+                if (errStdErr.includes('did not match any file(s) known to git') ||
+                    errStdErr.includes('is not a commit and a branch') ||
+                    errStdErr.includes('pathspec \'main\' did not match any file(s) known to git')) {
+                    Logger.debug(`[${onboardingId}] Local branch 'main' not found or invalid. Attempting to create it from 'upstream/main'.`);
+                    try {
+                        await execAsync('git checkout -b main upstream/main');
+                        Logger.debug(`[${onboardingId}] Created and switched to local branch 'main' from 'upstream/main'.`);
+                    } catch (createMainError: any) {
+                        const errMsg = createMainError instanceof Error ? createMainError.message : String(createMainError);
+                        Logger.error(`[${onboardingId}] Failed to create local branch 'main' from 'upstream/main': ${errMsg}. Stderr: ${createMainError.stderr}`);
+                        throw Object.assign(new Error(`Failed to create local branch 'main': ${errMsg}`), { step: 'setupBranch.setupMainBranch' });
+                    }
+                } else {
+                    const errMsg = checkoutMainError instanceof Error ? checkoutMainError.message : String(checkoutMainError);
+                    Logger.error(`[${onboardingId}] Failed to checkout local branch 'main': ${errMsg}. Stderr: ${checkoutMainError.stderr}`);
+                    throw Object.assign(new Error(`Failed to checkout local branch 'main': ${errMsg}`), { step: 'setupBranch.checkoutMainBranch' });
+                }
+            }
+
+            await execAsync('git reset --hard upstream/main');
+            Logger.debug(`[${onboardingId}] Local 'main' branch is now hard reset to 'upstream/main'.`);
+
+            const branchName = `feed/${config.name}`;
+            try {
+                await execAsync(`git branch -D ${branchName}`);
+                Logger.debug(`[${onboardingId}] Deleted local branch '${branchName}' as it may have existed.`);
+            } catch (deleteError: any) {
+                const errStdErrDelete = deleteError.stderr || '';
+                if (errStdErrDelete.includes('not found') || errStdErrDelete.includes('not found.')) {
+                    Logger.debug(`[${onboardingId}] Local branch '${branchName}' did not exist, no need to delete.`);
+                } else {
+                    const errorMessage = deleteError instanceof Error ? deleteError.message : String(deleteError);
+                    Logger.error(`[${onboardingId}] Failed to delete local branch '${branchName}': ${errorMessage}. Stderr: ${deleteError.stderr}`);
+                    throw Object.assign(new Error(`Failed to delete local branch '${branchName}': ${errorMessage}`), { step: 'setupBranch.deleteFeatureBranch' });
+                }
+            }
+
+            await execAsync(`git checkout -b ${branchName} upstream/main`);
+            Logger.debug(`[${onboardingId}] Created and checked out new branch '${branchName}' from 'upstream/main'.`);
+
+            return branchName;
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            Logger.error(`[${onboardingId}] Error during branch setup: ${errorMessage}`);
+            throw Object.assign(new Error(`Failed to setup branch: ${errorMessage}`), { step: 'setupBranch' });
+        }
+    }
+
+    /**
+     * Creates a pull request for the feed configuration changes.
+     * @param onboardingId The ID of the onboarding process.
+     * @param config The feed configuration.
+     * @param repoDir The root directory of the cloned repository.
+     * @param branchName The name of the branch to create the PR from.
+     * @returns Object containing the PR URL and branch name.
+     * @throws An error if PR creation fails.
+     */
+    public async createPullRequest(onboardingId: string, config: FeedConfiguration, repoDir: string, branchName: string): Promise<{ url: string; branchName: string }> {
+        try {
+            process.chdir(repoDir);
+
+            // Stage and commit changes
+            await execAsync('git add .');
+            await execAsync(`git commit --allow-empty -m "Add feed configuration for ${config.name}"`);
+            Logger.debug(`[${onboardingId}] Committed changes (or allowed empty commit) for ${config.name}.`);
+
+            // Push to origin
+            await execAsync(`git push -u -f origin ${branchName}`);
+            Logger.debug(`[${onboardingId}] Pushed branch ${branchName} to origin. Verifying remote branch...`);
+
+            try {
+                const { stdout: remoteBranchCheck } = await execAsync(`git ls-remote origin refs/heads/${branchName}`);
+                if (!remoteBranchCheck.includes(`refs/heads/${branchName}`)) {
+                    throw new Error(`Branch ${branchName} not found on remote 'origin' (fork) after push. Output of ls-remote: ${remoteBranchCheck}`);
+                }
+                Logger.debug(`[${onboardingId}] Branch ${branchName} confirmed on remote 'origin' (fork).`);
+            } catch (verifyError) {
+                const errorMessage = verifyError instanceof Error ? verifyError.message : String(verifyError);
+                Logger.error(`[${onboardingId}] Failed to verify branch ${branchName} on remote 'origin' (fork) after push: ${errorMessage}`);
+                throw new Error(`Verification of branch ${branchName} on remote 'origin' (fork) failed: ${errorMessage}`);
+            }
+
+            const title = `Add feed configuration for ${config.name}`;
+            const body = `Add new feed configuration:\n\n- Name: ${config.name}\n- Display Name: ${config.displayName}\n- Description: ${config.description}`;
+            const username = await this.getGitHubUsername();
+            const explicitHeadRef = `${username}:${branchName}`;
+
+            const prCheckCommand = `gh pr list --repo ${GITHUB_REPO.repoName} --head "${explicitHeadRef}" --state open --json url --limit 1`;
+            Logger.debug(`[${onboardingId}] Checking for existing PR with command: ${prCheckCommand}`);
+            const { stdout: existingPrJson } = await execAsync(prCheckCommand);
+
+            let prUrlToReturn: string;
+
+            const createPRCommand = `gh pr create --repo ${GITHUB_REPO.repoName} --base main --head ${explicitHeadRef} --title "${title}" --body "${body}"`
+
+            if (existingPrJson && existingPrJson.trim() !== '[]' && existingPrJson.trim() !== '') {
+                try {
+                    const prs = JSON.parse(existingPrJson);
+                    if (prs.length > 0 && prs[0].url) {
+                        prUrlToReturn = prs[0].url;
+                        Logger.log(`[${onboardingId}] Found existing open PR for ${explicitHeadRef} on ${GITHUB_REPO.repoName}: ${prUrlToReturn}`);
+                    } else {
+                        Logger.debug(`[${onboardingId}] No existing PR found or unable to parse PR list JSON. Proceeding to create PR.`);
+                        const { stdout: prUrl } = await execAsync(createPRCommand);
+                        prUrlToReturn = prUrl.trim();
+                    }
+                } catch (parseError) {
+                    Logger.log(`WARNING: [${onboardingId}] Could not parse existing PR JSON: ${existingPrJson}. Proceeding to create new PR. Error: ${parseError}`);
+                    const { stdout: prUrl } = await execAsync(createPRCommand);
+                    prUrlToReturn = prUrl.trim();
+                }
+            } else {
+                Logger.debug(`[${onboardingId}] No existing PR found. Proceeding to create PR.`);
+                const { stdout: prUrl } = await execAsync(createPRCommand);
+                prUrlToReturn = prUrl.trim();
+            }
+
+            Logger.debug(`[${onboardingId}] Pull request operation completed. PR URL: ${prUrlToReturn}`);
+            return { url: prUrlToReturn, branchName };
+        } catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            Logger.error(`[${onboardingId}] Error during createPullRequest: ${errorMessage}`);
+            throw Object.assign(new Error(`Failed to create pull request: ${errorMessage}`), { step: 'createPullRequest' });
+        }
+    }
+
+    /**
+     * Creates necessary directories for the onboarding process
+     * @param onboardingId The ID of the onboarding process
+     * @returns Object containing tempDir and repoDir paths
+     */
+    public createDirectories(onboardingId: string): { tempDir: string; repoDir: string } {
+        const tempDir = path.join(SETTINGS_DIR, 'onboard', 'temp', onboardingId);
+        const repoDir = path.join(tempDir, 'imcp-feed');
+        return { tempDir, repoDir };
+    }
+}
+
+export const onboardProcessor = new OnboardProcessor();