@covibes/zeroshot 5.3.0 → 5.4.0

package/src/issue-providers/README.md

@@ -0,0 +1,305 @@
+# Issue Providers
+
+Multi-platform issue support for Zeroshot. Fetch issues from GitHub, GitLab, Jira, and Azure DevOps.
+
+## Supported Providers
+
+| Provider         | CLI Tool | URL Pattern                                  | Issue Key Format      |
+| ---------------- | -------- | -------------------------------------------- | --------------------- |
+| **GitHub**       | `gh`     | `github.com/org/repo/issues/123`             | `123`, `org/repo#123` |
+| **GitLab**       | `glab`   | `gitlab.com/org/repo/-/issues/123`           | `123`, `org/repo#123` |
+| **Jira**         | `jira`   | `*.atlassian.net/browse/KEY-123`             | `KEY-123`             |
+| **Azure DevOps** | `az`     | `dev.azure.com/org/proj/_workitems/edit/123` | `123`                 |
+
+## Quick Start
+
+```bash
+# GitHub
+zeroshot run 123
+zeroshot run https://github.com/org/repo/issues/123
+zeroshot run org/repo#123
+
+# GitLab
+zeroshot run https://gitlab.com/org/repo/-/issues/123
+zeroshot run 123 --gitlab
+
+# Jira
+zeroshot run PROJ-123
+zeroshot run https://company.atlassian.net/browse/PROJ-123
+
+# Azure DevOps
+zeroshot run https://dev.azure.com/org/project/_workitems/edit/123
+zeroshot run 123 --devops
+```
+
+## Automatic Git Remote Detection
+
+When working in a git repository, zeroshot automatically detects the issue provider from your git remote URL:
+
+```bash
+# In a GitHub repository
+git remote get-url origin  # → https://github.com/org/repo.git
+zeroshot run 123            # Automatically uses GitHub
+
+# In a GitLab repository
+git remote get-url origin  # → https://gitlab.com/org/repo.git
+zeroshot run 456            # Automatically uses GitLab
+
+# In an Azure DevOps repository
+git remote get-url origin  # → https://dev.azure.com/org/project/_git/repo
+zeroshot run 789            # Automatically uses Azure DevOps
+```
+
+## Force Flags
+
+Override auto-detection with explicit provider flags:
+
+```bash
+-G, --github    # Force GitHub as issue source
+-L, --gitlab    # Force GitLab as issue source
+-J, --jira      # Force Jira as issue source
+-D, --devops    # Force Azure DevOps as issue source
+```
+
+**Example:**
+
+```bash
+# Force GitLab even when in a GitHub repo
+zeroshot run 123 --gitlab
+
+# Force Jira for bare number
+zeroshot run 456 --jira
+```
+
+## Detection Priority
+
+For bare issue numbers (e.g., `123`), zeroshot uses this priority:
+
+1. **Force flag** (`--github`, `--gitlab`, etc.) - Explicit CLI override
+2. **Git remote URL** - Auto-detected from your repository
+3. **Settings** (`defaultIssueSource`) - User preference
+4. **Legacy fallback** - GitHub (when no git context and no settings)
+
+For URLs and issue keys (like `PROJ-123`), the provider is detected from the format.
+
+## Settings
+
+Configure default provider and platform-specific settings:
+
+```bash
+# Set default provider for bare numbers
+zeroshot settings set defaultIssueSource gitlab
+
+# GitLab self-hosted instance
+zeroshot settings set gitlabInstance gitlab.company.com
+
+# Jira configuration
+zeroshot settings set jiraInstance jira.company.com
+zeroshot settings set jiraProject MYPROJECT  # Default project for bare numbers
+
+# Azure DevOps configuration
+zeroshot settings set azureOrg mycompany
+zeroshot settings set azureProject myproject  # Default project for bare numbers
+```
+
+### Settings Reference
+
+| Setting              | Type   | Default | Description                                |
+| -------------------- | ------ | ------- | ------------------------------------------ |
+| `defaultIssueSource` | string | github  | Provider for bare numbers (123)            |
+| `gitlabInstance`     | string | null    | Self-hosted GitLab URL                     |
+| `jiraInstance`       | string | null    | Self-hosted Jira URL                       |
+| `jiraProject`        | string | null    | Default Jira project key for bare numbers  |
+| `azureOrg`           | string | null    | Azure DevOps organization name             |
+| `azureProject`       | string | null    | Azure DevOps project name for bare numbers |
+
+## CLI Tool Setup
+
+Each provider requires its corresponding CLI tool:
+
+### GitHub
+
+```bash
+# Install
+brew install gh              # macOS
+apt install gh               # Linux
+# Or: https://cli.github.com/
+
+# Authenticate
+gh auth login
+gh auth status
+```
+
+### GitLab
+
+```bash
+# Install
+brew install glab            # macOS
+# Or: https://gitlab.com/gitlab-org/cli
+
+# Authenticate
+glab auth login
+glab auth status
+```
+
+### Jira
+
+```bash
+# Install go-jira
+brew install go-jira         # macOS
+# Or: https://github.com/go-jira/jira
+
+# Configure
+jira login
+jira version
+```
+
+### Azure DevOps
+
+```bash
+# Install Azure CLI
+brew install azure-cli       # macOS
+# Or: https://docs.microsoft.com/cli/azure/
+
+# Configure
+az login
+az devops configure --defaults organization=https://dev.azure.com/yourorg
+```
+
+## Self-Hosted Instances
+
+### GitLab Self-Hosted
+
+```bash
+# Configure self-hosted instance
+zeroshot settings set gitlabInstance gitlab.company.com
+
+# Now these work
+zeroshot run https://gitlab.company.com/org/repo/-/issues/123
+zeroshot run 123 --gitlab  # Uses self-hosted instance
+```
+
+### Jira Self-Hosted (Server/Data Center)
+
+```bash
+# Configure self-hosted instance and default project
+zeroshot settings set jiraInstance jira.company.com
+zeroshot settings set jiraProject MYPROJ
+
+# Now these work
+zeroshot run https://jira.company.com/browse/MYPROJ-123
+zeroshot run MYPROJ-123
+zeroshot run 123 --jira  # Becomes MYPROJ-123
+```
+
+## Examples
+
+### Team Using GitLab
+
+```bash
+# Set once per machine
+zeroshot settings set defaultIssueSource gitlab
+
+# Then just use bare numbers
+zeroshot run 456
+```
+
+### Team Using Jira
+
+```bash
+# Set once per machine
+zeroshot settings set defaultIssueSource jira
+zeroshot settings set jiraProject MYTEAM
+
+# Then just use bare numbers (becomes MYTEAM-789)
+zeroshot run 789
+```
+
+### Mixed Team
+
+```bash
+# Use explicit URLs or flags when working across platforms
+zeroshot run https://github.com/org/repo/issues/100
+zeroshot run https://gitlab.com/org/repo/-/issues/200
+zeroshot run PROJ-300
+```
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/zeroshot.yml
+- name: Run Zeroshot on Issue
+  run: zeroshot run ${{ github.event.issue.html_url }} --ship
+
+# .gitlab-ci.yml
+- script: zeroshot run $CI_MERGE_REQUEST_IID --gitlab --ship
+
+# Azure Pipelines
+- script: zeroshot run $(System.WorkItemId) --devops --ship
+```
+
+## Troubleshooting
+
+### Provider Not Detected
+
+**Problem:** Bare number not detected as expected provider
+
+```bash
+$ zeroshot run 123
+# Fetches from GitHub, but I wanted GitLab
+```
+
+**Solution:** Set `defaultIssueSource` or use force flag
+
+```bash
+zeroshot settings set defaultIssueSource gitlab
+# OR
+zeroshot run 123 --gitlab
+```
+
+### CLI Tool Not Installed
+
+**Problem:** Preflight check fails
+
+```bash
+PREFLIGHT CHECK FAILED
+GitLab CLI (glab) not installed
+```
+
+**Solution:** Install the required CLI tool
+
+```bash
+brew install glab
+glab auth login
+```
+
+### Self-Hosted Instance Not Recognized
+
+**Problem:** Self-hosted URL not detected
+
+```bash
+$ zeroshot run https://gitlab.mycompany.com/org/repo/-/issues/123
+Error: No issue provider matched input
+```
+
+**Solution:** Configure the instance setting
+
+```bash
+zeroshot settings set gitlabInstance gitlab.mycompany.com
+```
+
+### Jira Bare Numbers Don't Work
+
+**Problem:** Bare numbers don't convert to Jira keys
+
+```bash
+$ zeroshot run 123 --jira
+Error: Failed to fetch Jira issue
+```
+
+**Solution:** Configure `jiraProject` setting
+
+```bash
+zeroshot settings set jiraProject MYPROJECT
+# Now: 123 becomes MYPROJECT-123
+```

package/src/issue-providers/azure-devops-provider.js

@@ -0,0 +1,273 @@
+/**
+ * Azure DevOps Provider - Fetch work items via az CLI
+ * Supports Azure DevOps cloud (dev.azure.com)
+ */
+
+const IssueProvider = require('./base-provider');
+const { execSync } = require('../lib/safe-exec');
+const { detectGitContext } = require('../../lib/git-remote-utils');
+
+class AzureDevOpsProvider extends IssueProvider {
+  static id = 'azure-devops';
+  static displayName = 'Azure DevOps';
+
+  /**
+   * Azure DevOps supports PR creation via az CLI
+   */
+  static supportsPR() {
+    return true;
+  }
+
+  /**
+   * Get PR CLI tool info for preflight checks
+   */
+  static getPRTool() {
+    return {
+      name: 'az',
+      checkCmd: 'az --version',
+      installHint: 'https://docs.microsoft.com/cli/azure/',
+      displayName: 'Azure DevOps',
+    };
+  }
+
+  /**
+   * Detect Azure DevOps work item URLs
+   * Matches:
+   * - dev.azure.com URLs
+   * - *.visualstudio.com URLs
+   * - Bare numbers when git remote is Azure DevOps (auto-detected)
+   * - Bare numbers when defaultIssueSource=azure-devops (requires azureOrg setting)
+   *
+   * @param {string} input - Issue identifier (URL or number)
+   * @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) {
+    // dev.azure.com URLs
+    if (/dev\.azure\.com\/.*\/_workitems\/edit\/\d+/.test(input)) {
+      return true;
+    }
+
+    // Legacy visualstudio.com URLs (e.g., https://org.visualstudio.com/project/_workitems/edit/123)
+    if (/https?:\/\/[^.]+\.visualstudio\.com\/[^/]+\/_workitems\/edit\/\d+/.test(input)) {
+      return true;
+    }
+
+    // Bare numbers - use shared priority cascade logic
+    // Azure DevOps requires azureOrg setting when using defaultIssueSource
+    return IssueProvider.detectBareNumber(input, settings, gitContext, 'azure-devops', {
+      requiredSettings: ['azureOrg'],
+    });
+  }
+
+  static getRequiredTool() {
+    return {
+      name: 'az',
+      checkCmd: 'az --version',
+      installHint:
+        'Install Azure CLI: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli\nThen: az extension add --name azure-devops',
+    };
+  }
+
+  /**
+   * Check az CLI authentication for Azure DevOps
+   */
+  static checkAuth() {
+    try {
+      // First check Azure login
+      execSync('az account show', { encoding: 'utf8', stdio: 'pipe' });
+    } catch (err) {
+      const stderr = err.stderr || err.message || '';
+
+      if (stderr.includes('az login') || stderr.includes('not logged in')) {
+        return {
+          authenticated: false,
+          error: 'Azure CLI not authenticated',
+          recovery: [
+            'Run: az login',
+            'Then verify: az account show',
+            'Ensure azure-devops extension: az extension add --name azure-devops',
+          ],
+        };
+      }
+
+      return {
+        authenticated: false,
+        error: stderr.trim() || 'Unknown Azure CLI error',
+        recovery: ['Run: az login', 'Then verify: az account show'],
+      };
+    }
+
+    // Check azure-devops extension is installed
+    try {
+      const output = execSync('az extension list --query "[?name==\'azure-devops\']" -o json', {
+        encoding: 'utf8',
+        stdio: 'pipe',
+      });
+      const extensions = JSON.parse(output);
+      if (extensions.length === 0) {
+        return {
+          authenticated: false,
+          error: 'Azure DevOps extension not installed',
+          recovery: [
+            'Install the extension: az extension add --name azure-devops',
+            'Then verify: az extension list | grep azure-devops',
+          ],
+        };
+      }
+    } catch {
+      return {
+        authenticated: false,
+        error: 'Could not verify Azure DevOps extension',
+        recovery: ['Install the extension: az extension add --name azure-devops'],
+      };
+    }
+
+    return { authenticated: true, error: null, recovery: [] };
+  }
+
+  /**
+   * Azure DevOps-specific settings schema
+   */
+  static getSettingsSchema() {
+    return {
+      azureOrg: {
+        type: 'string',
+        nullable: true,
+        default: null,
+        description: "Azure DevOps org URL (e.g., 'https://dev.azure.com/myorg')",
+      },
+      azureProject: {
+        type: 'string',
+        nullable: true,
+        default: null,
+        description: "Azure DevOps project name (e.g., 'MyProject')",
+      },
+    };
+  }
+
+  fetchIssue(identifier, settings) {
+    try {
+      const { workItemId, org, project: _project } = this._parseIdentifier(identifier, settings);
+
+      if (!org) {
+        throw new Error(
+          'Azure DevOps requires azureOrg setting. Set via: zeroshot settings set azureOrg <url>'
+        );
+      }
+
+      // Fetch work item using az CLI
+      // Note: Work item IDs are unique per organization, no --project flag needed
+      const cmd = `az boards work-item show --id ${workItemId} --org "${org}" -o json`;
+      const output = execSync(cmd, { encoding: 'utf8' });
+      const workItem = JSON.parse(output);
+
+      return this._parseWorkItem(workItem);
+    } catch (error) {
+      throw new Error(`Failed to fetch Azure DevOps work item: ${error.message}`);
+    }
+  }
+
+  /**
+   * Parse identifier to extract work item ID, org, and project
+   * Uses git context for auto-detection when settings not provided
+   * @private
+   */
+  _parseIdentifier(identifier, settings) {
+    // URL format: https://dev.azure.com/org/project/_workitems/edit/123
+    // Use [^/]+ to match any characters except /, supporting spaces and special chars
+    const urlMatch = identifier.match(/dev\.azure\.com\/([^/]+)\/([^/]+)\/_workitems\/edit\/(\d+)/);
+    if (urlMatch) {
+      return {
+        org: `https://dev.azure.com/${urlMatch[1]}`,
+        project: decodeURIComponent(urlMatch[2]), // Decode URL-encoded project names
+        workItemId: urlMatch[3],
+      };
+    }
+
+    // Legacy URL format: https://org.visualstudio.com/project/_workitems/edit/123
+    const legacyMatch = identifier.match(
+      /https?:\/\/([^.]+)\.visualstudio\.com\/([^/]+)\/_workitems\/edit\/(\d+)/
+    );
+    if (legacyMatch) {
+      return {
+        org: `https://${legacyMatch[1]}.visualstudio.com`,
+        project: decodeURIComponent(legacyMatch[2]), // Decode URL-encoded project names
+        workItemId: legacyMatch[3],
+      };
+    }
+
+    // Bare number: try settings first, then git context
+    if (/^\d+$/.test(identifier)) {
+      let org = settings.azureOrg;
+      let project = settings.azureProject;
+
+      // If settings don't have org, try git context
+      if (!org) {
+        const gitContext = detectGitContext();
+        if (gitContext?.provider === 'azure-devops') {
+          org = gitContext.azureOrg;
+          project = gitContext.azureProject;
+        }
+      }
+
+      return {
+        org,
+        project,
+        workItemId: identifier,
+      };
+    }
+
+    throw new Error(`Could not parse Azure DevOps work item identifier: ${identifier}`);
+  }
+
+  /**
+   * Parse Azure DevOps work item into standardized InputData format
+   * @private
+   */
+  _parseWorkItem(workItem) {
+    const fields = workItem.fields || {};
+    const id = workItem.id;
+    const title = fields['System.Title'] || '';
+    const description = fields['System.Description'] || '';
+    const tags = fields['System.Tags'] ? fields['System.Tags'].split(';').map((t) => t.trim()) : [];
+
+    let context = `# Azure DevOps Work Item #${id}\n\n`;
+    context += `## Title\n${title}\n\n`;
+
+    if (description) {
+      // Strip HTML tags from description (Azure stores as HTML)
+      const plainDescription = description.replace(/<[^>]*>/g, '');
+      context += `## Description\n${plainDescription}\n\n`;
+    }
+
+    if (tags.length > 0) {
+      context += `## Tags\n`;
+      context += tags.map((t) => `- ${t}`).join('\n');
+      context += '\n\n';
+    }
+
+    // Map tags to labels format
+    const labels = tags.map((name) => ({ name }));
+
+    // Azure work items don't have comments in the same API call
+    // Would need separate call to fetch comments, omitting for now
+    const comments = [];
+
+    // Strip HTML from description for body field
+    const plainBody = description.replace(/<[^>]*>/g, '');
+
+    return {
+      number: id,
+      title,
+      body: plainBody,
+      labels,
+      comments,
+      url: workItem.url || null,
+      context,
+    };
+  }
+}
+
+module.exports = AzureDevOpsProvider;