@the-open-engine/zeroshot 5.4.0

package/src/issue-providers/base-provider.js

@@ -0,0 +1,232 @@
+/**
+ * Base Provider - Abstract base class for issue providers
+ *
+ * This class represents a "platform" that can:
+ * 1. Fetch issues (all providers)
+ * 2. Create PRs/MRs (git-hosting providers only: GitHub, GitLab, Azure DevOps)
+ *
+ * Defines interface for fetching issues from different sources (GitHub, GitLab, Jira, etc)
+ * Each provider must implement:
+ * - Static properties: id, displayName
+ * - Static methods: detectIdentifier(), getRequiredTool()
+ * - Instance method: fetchIssue()
+ *
+ * Git-hosting providers should also implement:
+ * - Static method: supportsPR() returning true
+ * - Static method: getPRTool() for PR/MR CLI tool info
+ */
+
+class IssueProvider {
+  /**
+   * Provider identifier (e.g., 'github', 'gitlab')
+   * @type {string}
+   */
+  static id = null;
+
+  /**
+   * Human-readable provider name
+   * @type {string}
+   */
+  static displayName = null;
+
+  /**
+   * Whether this provider supports PR/MR creation.
+   * Override in subclass to return true for git-hosting platforms.
+   * @returns {boolean}
+   */
+  static supportsPR() {
+    return false;
+  }
+
+  /**
+   * Get PR/MR CLI tool info for preflight checks.
+   * Only git-hosting providers (GitHub, GitLab, Azure DevOps) implement this.
+   * @returns {{ name: string, checkCmd: string, installHint: string, displayName: string }|null}
+   */
+  static getPRTool() {
+    return null;
+  }
+
+  /**
+   * Detect if input matches this provider's patterns
+   * @param {string} _input - User input (URL, issue key, number)
+   * @param {Object} _settings - User settings from settings.js
+   * @param {Object|null} _gitContext - Auto-detected git remote context
+   * @returns {boolean}
+   */
+  static detectIdentifier(_input, _settings, _gitContext) {
+    throw new Error(`${this.name}.detectIdentifier() must be implemented by subclass`);
+  }
+
+  /**
+   * Shared detection logic for bare numbers (e.g., "123").
+   * Implements the priority cascade:
+   *   1. Git context (highest priority) - auto-detected from git remote
+   *   2. Settings (defaultIssueSource)
+   *   3. Legacy fallback (GitHub only, for backward compatibility)
+   *
+   * Call this from subclass detectIdentifier() for bare number handling.
+   *
+   * @param {string} input - User input to check
+   * @param {Object} settings - User settings
+   * @param {Object|null} gitContext - Git context from detectGitContext()
+   * @param {string} providerId - This provider's ID (e.g., 'github', 'gitlab')
+   * @param {Object} [options] - Additional options
+   * @param {boolean} [options.requiresAdditionalSettings] - If true, check additional settings exist
+   * @param {string[]} [options.requiredSettings] - Settings keys that must exist for this provider
+   * @returns {boolean} True if this provider should handle the bare number
+   */
+  static detectBareNumber(input, settings, gitContext, providerId, options = {}) {
+    // Only handle bare numbers
+    if (!/^\d+$/.test(input)) {
+      return false;
+    }
+
+    // 1. Git context takes highest priority
+    if (gitContext?.provider) {
+      return gitContext.provider === providerId;
+    }
+
+    // 2. Check settings.defaultIssueSource
+    if (settings.defaultIssueSource) {
+      if (settings.defaultIssueSource !== providerId) {
+        return false;
+      }
+      // If provider requires additional settings, validate them
+      if (options.requiredSettings?.length > 0) {
+        return options.requiredSettings.every((key) => settings[key]);
+      }
+      return true;
+    }
+
+    // 3. Legacy fallback - only GitHub gets the fallback for backward compatibility
+    return providerId === 'github';
+  }
+
+  /**
+   * Shared detection logic for org/repo#123 format.
+   * Some providers (GitHub, GitLab) use this format.
+   *
+   * @param {string} input - User input to check
+   * @param {Object} settings - User settings
+   * @param {Object|null} gitContext - Git context
+   * @param {string} providerId - This provider's ID
+   * @returns {boolean} True if this provider should handle the input
+   */
+  static detectRepoIssueFormat(input, settings, gitContext, providerId) {
+    // Match org/repo#123 format
+    if (!/^[\w.-]+\/[\w.-]+#\d+$/.test(input)) {
+      return false;
+    }
+
+    // 1. Git context takes priority
+    if (gitContext?.provider) {
+      return gitContext.provider === providerId;
+    }
+
+    // 2. Settings fallback
+    return settings.defaultIssueSource === providerId;
+  }
+
+  /**
+   * Get required CLI tool info
+   * @returns {{ name: string, checkCmd: string, installHint: string }}
+   */
+  static getRequiredTool() {
+    throw new Error(`${this.name}.getRequiredTool() must be implemented by subclass`);
+  }
+
+  /**
+   * Check if the provider's CLI is authenticated.
+   * Override in subclass to implement provider-specific auth checks.
+   *
+   * @param {string|null} hostname - Optional hostname for providers with multi-instance support
+   *   (e.g., GitLab with gitlab.com + self-hosted). When provided, only check auth for that
+   *   specific instance to avoid false failures from other unconfigured instances.
+   * @returns {{ authenticated: boolean, error: string|null, recovery: string[] }}
+   *   - authenticated: true if auth is valid
+   *   - error: error message if not authenticated, null otherwise
+   *   - recovery: array of steps to fix auth issues
+   */
+  static checkAuth(_hostname = null) {
+    // Default: no auth check required (some CLIs like jira use config files)
+    return { authenticated: true, error: null, recovery: [] };
+  }
+
+  /**
+   * Get settings schema for this provider.
+   * Override in subclass to define provider-specific settings.
+   *
+   * Schema format:
+   * {
+   *   settingKey: {
+   *     type: 'string' | 'number' | 'boolean',
+   *     nullable: true | false,
+   *     default: <default value>,
+   *     description: 'Human-readable description',
+   *     pattern?: RegExp,         // Optional validation pattern
+   *     patternMsg?: string       // Error message if pattern fails
+   *   }
+   * }
+   *
+   * @returns {Object.<string, Object>} Settings schema
+   */
+  static getSettingsSchema() {
+    return {};
+  }
+
+  /**
+   * Validate a setting value for this provider.
+   * Uses schema from getSettingsSchema() by default.
+   *
+   * @param {string} key - Setting key
+   * @param {any} value - Setting value
+   * @returns {string|null|undefined} Error message if invalid, null if valid, undefined if not this provider's setting
+   */
+  static validateSetting(key, value) {
+    const schema = this.getSettingsSchema();
+    const config = schema[key];
+
+    if (!config) {
+      return undefined; // Not this provider's setting
+    }
+
+    // Nullable check
+    if (config.nullable && value === null) {
+      return null; // null is valid
+    }
+
+    // Type validation
+    if (config.type === 'string' && typeof value !== 'string') {
+      return `${key} must be a string${config.nullable ? ' or null' : ''}`;
+    }
+
+    // Pattern validation
+    if (config.pattern && typeof value === 'string' && !config.pattern.test(value)) {
+      return config.patternMsg || `${key} has invalid format`;
+    }
+
+    return null; // Valid
+  }
+
+  /**
+   * Fetch issue from provider
+   * @param {string} _identifier - Issue identifier (URL, key, number)
+   * @param {Object} _settings - User settings from settings.js
+   * @returns {Promise<Object>} InputData object with structure:
+   *   {
+   *     number: Number|null,
+   *     title: String,
+   *     body: String,
+   *     labels: Array<{name: String}>,
+   *     comments: Array<{author, createdAt, body}>,
+   *     url: String|null,
+   *     context: String  // Formatted markdown
+   *   }
+   */
+  fetchIssue(_identifier, _settings) {
+    throw new Error(`${this.constructor.name}.fetchIssue() must be implemented by subclass`);
+  }
+}
+
+module.exports = IssueProvider;

package/src/issue-providers/github-provider.js

@@ -0,0 +1,210 @@
+/**
+ * GitHub Provider - Fetch issues from GitHub via gh CLI
+ */
+
+const IssueProvider = require('./base-provider');
+const { execSync } = require('../lib/safe-exec');
+
+const AUTH_CHECK_TIMEOUT_MS = 2000;
+
+class GitHubProvider extends IssueProvider {
+  static id = 'github';
+  static displayName = 'GitHub';
+
+  /**
+   * GitHub supports PR creation via gh CLI
+   */
+  static supportsPR() {
+    return true;
+  }
+
+  /**
+   * Get PR CLI tool info for preflight checks
+   */
+  static getPRTool() {
+    return {
+      name: 'gh',
+      checkCmd: 'gh --version',
+      installHint: 'https://cli.github.com/',
+      displayName: 'GitHub',
+    };
+  }
+
+  /**
+   * Detect GitHub URLs and issue references
+   * Matches:
+   * - github.com URLs
+   * - org/repo#123 format
+   * - Bare numbers when git remote is GitHub (auto-detected)
+   * - Bare numbers when defaultIssueSource=github
+   *
+   * @param {string} input - Issue identifier (URL, number, or org/repo#123)
+   * @param {Object} settings - User settings
+   * @param {Object|null} gitContext - Auto-detected git remote context
+   * @returns {boolean} True if this provider should handle the input
+   */
+  static detectIdentifier(input, settings, gitContext = null) {
+    // GitHub URLs
+    if (input.includes('github.com') && /\/issues\/\d+/.test(input)) {
+      return true;
+    }
+
+    // org/repo#123 format - use shared logic
+    if (IssueProvider.detectRepoIssueFormat(input, settings, gitContext, 'github')) {
+      return true;
+    }
+
+    // Bare numbers - use shared priority cascade logic
+    return IssueProvider.detectBareNumber(input, settings, gitContext, 'github');
+  }
+
+  static getRequiredTool() {
+    return {
+      name: 'gh',
+      checkCmd: 'gh --version',
+      installHint: 'Install gh CLI: https://cli.github.com/',
+    };
+  }
+
+  /**
+   * Check gh CLI authentication
+   */
+  static checkAuth() {
+    try {
+      execSync('gh auth status', {
+        encoding: 'utf8',
+        stdio: 'pipe',
+        timeout: AUTH_CHECK_TIMEOUT_MS,
+      });
+      return { authenticated: true, error: null, recovery: [] };
+    } catch (err) {
+      const stderr = err.stderr || err.message || '';
+
+      if (err.code === 'ENOENT' || stderr.includes('command not found')) {
+        return {
+          authenticated: false,
+          error: 'gh CLI not installed',
+          recovery: ['Install gh: https://cli.github.com/', 'Then verify: gh --version'],
+        };
+      }
+
+      if (stderr.includes('Command timed out')) {
+        return {
+          authenticated: false,
+          error: 'gh auth status timed out',
+          recovery: ['Retry: gh auth status', 'If it still hangs, re-run: gh auth login'],
+        };
+      }
+
+      if (stderr.includes('not logged in')) {
+        return {
+          authenticated: false,
+          error: 'gh CLI not authenticated',
+          recovery: [
+            'Run: gh auth login',
+            'Select GitHub.com, HTTPS, and authenticate via browser',
+            'Then verify: gh auth status',
+          ],
+        };
+      }
+
+      return {
+        authenticated: false,
+        error: stderr.trim() || 'Unknown gh auth error',
+        recovery: ['Run: gh auth login', 'Then verify: gh auth status'],
+      };
+    }
+  }
+
+  /**
+   * GitHub-specific settings schema
+   * GitHub has no extra settings (cloud-only, no self-hosted config needed)
+   */
+  static getSettingsSchema() {
+    return {};
+  }
+
+  fetchIssue(identifier, _settings, gitContext = null) {
+    try {
+      const { repo, number } = this._parseIdentifier(identifier, gitContext);
+
+      // ALWAYS use -R flag when repo is known - never rely on CWD git remote
+      const repoFlag = repo ? `-R ${repo}` : '';
+      const cmd = `gh issue view ${number} ${repoFlag} --json number,title,body,labels,assignees,comments,url`;
+      const output = execSync(cmd, { encoding: 'utf8' });
+      const issue = JSON.parse(output);
+
+      return this._parseIssue(issue);
+    } catch (error) {
+      throw new Error(`Failed to fetch GitHub issue: ${error.message}`);
+    }
+  }
+
+  /**
+   * Parse identifier into repo and issue number
+   * @private
+   * @returns {{ repo: string|null, number: string }}
+   */
+  _parseIdentifier(identifier, gitContext = null) {
+    // GitHub URL: https://github.com/org/repo/issues/123
+    const urlMatch = identifier.match(/github\.com\/([^/]+\/[^/]+)\/issues\/(\d+)/);
+    if (urlMatch) {
+      return { repo: urlMatch[1], number: urlMatch[2] };
+    }
+
+    // org/repo#123 format
+    const repoMatch = identifier.match(/^([\w.-]+\/[\w.-]+)#(\d+)$/);
+    if (repoMatch) {
+      return { repo: repoMatch[1], number: repoMatch[2] };
+    }
+
+    // Bare number - use gitContext if available
+    if (/^\d+$/.test(identifier)) {
+      const repo =
+        gitContext?.owner && gitContext?.repo ? `${gitContext.owner}/${gitContext.repo}` : null;
+      return { repo, number: identifier };
+    }
+
+    // Fallback: assume it's a number, no repo
+    return { repo: null, number: identifier };
+  }
+
+  /**
+   * Parse issue into standardized InputData format
+   * @private
+   */
+  _parseIssue(issue) {
+    let context = `# GitHub Issue #${issue.number}\n\n`;
+    context += `## Title\n${issue.title}\n\n`;
+
+    if (issue.body) {
+      context += `## Description\n${issue.body}\n\n`;
+    }
+
+    if (issue.labels && issue.labels.length > 0) {
+      context += `## Labels\n`;
+      context += issue.labels.map((l) => `- ${l.name}`).join('\n');
+      context += '\n\n';
+    }
+
+    if (issue.comments && issue.comments.length > 0) {
+      context += `## Comments\n\n`;
+      for (const comment of issue.comments) {
+        context += `### ${comment.author.login} (${new Date(comment.createdAt).toISOString()})\n`;
+        context += `${comment.body}\n\n`;
+      }
+    }
+
+    return {
+      number: issue.number,
+      title: issue.title,
+      body: issue.body,
+      labels: issue.labels || [],
+      comments: issue.comments || [],
+      url: issue.url || null,
+      context,
+    };
+  }
+}
+
+module.exports = GitHubProvider;

package/src/issue-providers/gitlab-provider.js

@@ -0,0 +1,262 @@
+/**
+ * GitLab Provider - Fetch issues from GitLab via glab CLI
+ * Supports both cloud (gitlab.com) and self-hosted instances
+ */
+
+const IssueProvider = require('./base-provider');
+const { execSync } = require('../lib/safe-exec');
+
+const AUTH_CHECK_TIMEOUT_MS = 2000;
+
+class GitLabProvider extends IssueProvider {
+  static id = 'gitlab';
+  static displayName = 'GitLab';
+
+  /**
+   * GitLab supports MR creation via glab CLI
+   */
+  static supportsPR() {
+    return true;
+  }
+
+  /**
+   * Get MR CLI tool info for preflight checks
+   */
+  static getPRTool() {
+    return {
+      name: 'glab',
+      checkCmd: 'glab --version',
+      installHint: 'brew install glab (or https://gitlab.com/gitlab-org/cli)',
+      displayName: 'GitLab',
+    };
+  }
+
+  /**
+   * Detect GitLab URLs and issue references
+   * Matches:
+   * - gitlab.com URLs
+   * - Self-hosted GitLab URLs (via gitlabInstance setting)
+   * - org/repo#123 when git remote is GitLab (auto-detected)
+   * - org/repo#123 when defaultIssueSource=gitlab
+   * - Bare numbers when git remote is GitLab (auto-detected)
+   * - Bare numbers when defaultIssueSource=gitlab
+   *
+   * @param {string} input - Issue identifier (URL, number, or org/repo#123)
+   * @param {Object} settings - User settings
+   * @param {Object|null} gitContext - Auto-detected git remote context
+   * @returns {boolean} True if this provider should handle the input
+   */
+  static detectIdentifier(input, settings, gitContext = null) {
+    // GitLab cloud URLs
+    if (input.includes('gitlab.com') && /\/-\/issues\/\d+/.test(input)) {
+      return true;
+    }
+
+    // Self-hosted GitLab URLs
+    if (
+      settings.gitlabInstance &&
+      input.includes(settings.gitlabInstance) &&
+      /\/-\/issues\/\d+/.test(input)
+    ) {
+      return true;
+    }
+
+    // org/repo#123 format - use shared logic
+    if (IssueProvider.detectRepoIssueFormat(input, settings, gitContext, 'gitlab')) {
+      return true;
+    }
+
+    // Bare numbers - use shared priority cascade logic
+    return IssueProvider.detectBareNumber(input, settings, gitContext, 'gitlab');
+  }
+
+  static getRequiredTool() {
+    return {
+      name: 'glab',
+      checkCmd: 'glab --version',
+      installHint: 'Install glab CLI: brew install glab (or https://gitlab.com/gitlab-org/cli)',
+    };
+  }
+
+  /**
+   * Check glab CLI authentication for a specific hostname.
+   * If hostname is provided, only checks that specific instance.
+   * Otherwise, uses glab's default context detection (git remote).
+   *
+   * @param {string|null} hostname - GitLab hostname to check (e.g., 'gitlab.com', 'gitlab.lrz.de')
+   */
+  static checkAuth(hostname = null) {
+    // Use --hostname flag to check specific instance, avoiding false failures
+    // when other configured instances are unauthenticated
+    const cmd = hostname ? `glab auth status --hostname ${hostname}` : 'glab auth status';
+
+    try {
+      execSync(cmd, { encoding: 'utf8', stdio: 'pipe', timeout: AUTH_CHECK_TIMEOUT_MS });
+      return { authenticated: true, error: null, recovery: [] };
+    } catch (err) {
+      const stderr = err.stderr || err.message || '';
+
+      if (err.code === 'ENOENT' || stderr.includes('command not found')) {
+        return {
+          authenticated: false,
+          error: 'glab CLI not installed',
+          recovery: [
+            'Install glab: https://gitlab.com/gitlab-org/cli',
+            'Then verify: glab --version',
+          ],
+        };
+      }
+
+      if (stderr.includes('Command timed out')) {
+        return {
+          authenticated: false,
+          error: 'glab auth status timed out',
+          recovery: ['Retry: glab auth status', 'If it still hangs, run: glab auth login'],
+        };
+      }
+
+      const hostnameHint = hostname || 'your GitLab instance';
+      if (
+        stderr.includes('not logged in') ||
+        stderr.includes('no authentication') ||
+        stderr.includes('No token found')
+      ) {
+        return {
+          authenticated: false,
+          error: `glab CLI not authenticated for ${hostnameHint}`,
+          recovery: [
+            hostname ? `Run: glab auth login --hostname ${hostname}` : 'Run: glab auth login',
+            'Authenticate via browser when prompted',
+            `Then verify: glab auth status${hostname ? ` --hostname ${hostname}` : ''}`,
+          ],
+        };
+      }
+
+      return {
+        authenticated: false,
+        error: stderr.trim() || 'Unknown glab auth error',
+        recovery: [
+          hostname ? `Run: glab auth login --hostname ${hostname}` : 'Run: glab auth login',
+          'Then verify: glab auth status',
+        ],
+      };
+    }
+  }
+
+  /**
+   * GitLab-specific settings schema
+   */
+  static getSettingsSchema() {
+    return {
+      gitlabInstance: {
+        type: 'string',
+        nullable: true,
+        default: null,
+        description: "Self-hosted GitLab URL (e.g., 'gitlab.company.com')",
+      },
+    };
+  }
+
+  fetchIssue(identifier, _settings) {
+    try {
+      // glab accepts full URLs directly - use that for simplicity
+      const isUrl = /^https?:\/\//.test(identifier);
+      let cmd;
+
+      if (isUrl) {
+        // Pass URL directly to glab - handles self-hosted instances automatically
+        cmd = `glab issue view "${identifier}" --output json`;
+      } else {
+        // For org/repo#123 or bare numbers, parse and build command
+        const { issueNumber, repo } = this._parseIdentifier(identifier);
+        cmd = `glab issue view ${issueNumber} --output json`;
+        if (repo) {
+          cmd += ` --repo ${repo}`;
+        }
+      }
+
+      const output = execSync(cmd, { encoding: 'utf8' });
+      const issue = JSON.parse(output);
+
+      return this._parseIssue(issue);
+    } catch (error) {
+      throw new Error(`Failed to fetch GitLab issue: ${error.message}`);
+    }
+  }
+
+  /**
+   * Parse identifier to extract issue number, repo, and hostname
+   * @private
+   */
+  _parseIdentifier(identifier) {
+    // URL format: https://gitlab.example.com/org/repo/-/issues/123
+    const urlMatch = identifier.match(/https?:\/\/([^/]+)\/([^/]+\/[^/]+)\/-\/issues\/(\d+)/);
+    if (urlMatch) {
+      const hostname = urlMatch[1];
+      return {
+        hostname: hostname !== 'gitlab.com' ? hostname : null,
+        repo: urlMatch[2],
+        issueNumber: urlMatch[3],
+      };
+    }
+
+    // org/repo#123 format
+    const repoMatch = identifier.match(/^([\w-]+\/[\w-]+)#(\d+)$/);
+    if (repoMatch) {
+      return { hostname: null, repo: repoMatch[1], issueNumber: repoMatch[2] };
+    }
+
+    // Bare number (relies on glab's default repo)
+    return { hostname: null, repo: null, issueNumber: identifier };
+  }
+
+  /**
+   * Parse GitLab issue into standardized InputData format
+   * @private
+   */
+  _parseIssue(issue) {
+    let context = `# GitLab Issue #${issue.iid || issue.id}\n\n`;
+    context += `## Title\n${issue.title}\n\n`;
+
+    if (issue.description) {
+      context += `## Description\n${issue.description}\n\n`;
+    }
+
+    if (issue.labels && issue.labels.length > 0) {
+      context += `## Labels\n`;
+      context += issue.labels.map((l) => `- ${l}`).join('\n');
+      context += '\n\n';
+    }
+
+    if (issue.notes && issue.notes.length > 0) {
+      context += `## Comments\n\n`;
+      for (const note of issue.notes) {
+        const author = note.author?.username || 'unknown';
+        context += `### ${author} (${note.created_at})\n`;
+        context += `${note.body}\n\n`;
+      }
+    }
+
+    // Map GitLab labels to GitHub format
+    const labels = (issue.labels || []).map((name) => ({ name }));
+
+    // Map GitLab notes to GitHub comment format
+    const comments = (issue.notes || []).map((note) => ({
+      author: { login: note.author?.username || 'unknown' },
+      createdAt: note.created_at,
+      body: note.body,
+    }));
+
+    return {
+      number: issue.iid || issue.id || null,
+      title: issue.title,
+      body: issue.description || '',
+      labels,
+      comments,
+      url: issue.web_url || null,
+      context,
+    };
+  }
+}
+
+module.exports = GitLabProvider;