specweave 0.4.0 → 0.6.0

package/plugins/specweave-github/lib/github-client.ts

@@ -0,0 +1,330 @@
+/**
+ * GitHub CLI wrapper for SpecWeave
+ * Uses `gh` command for GitHub API operations
+ */
+
+import { execSync } from 'child_process';
+import { GitHubIssue, GitHubMilestone } from './types';
+
+export class GitHubClient {
+  private repo: string;
+
+  constructor(repo?: string) {
+    // Auto-detect repo from git remote if not provided
+    this.repo = repo || this.detectRepo();
+  }
+
+  /**
+   * Auto-detect GitHub repository from git remote
+   */
+  private detectRepo(): string {
+    try {
+      const remote = execSync('git remote get-url origin', { encoding: 'utf-8' }).trim();
+      const match = remote.match(/github\.com[:/](.+\/.+?)(?:\.git)?$/);
+      if (!match) {
+        throw new Error('Could not detect GitHub repository from git remote');
+      }
+      return match[1];
+    } catch (error) {
+      throw new Error('Not a git repository or no GitHub remote configured');
+    }
+  }
+
+  /**
+   * Check if GitHub CLI is installed and authenticated
+   */
+  static checkGitHubCLI(): { installed: boolean; authenticated: boolean; error?: string } {
+    try {
+      execSync('gh --version', { encoding: 'utf-8', stdio: 'pipe' });
+    } catch {
+      return { installed: false, authenticated: false, error: 'GitHub CLI (gh) not installed' };
+    }
+
+    try {
+      execSync('gh auth status', { encoding: 'utf-8', stdio: 'pipe' });
+      return { installed: true, authenticated: true };
+    } catch {
+      return { installed: true, authenticated: false, error: 'GitHub CLI not authenticated. Run: gh auth login' };
+    }
+  }
+
+  /**
+   * Create or get existing milestone
+   *
+   * @param title Milestone title
+   * @param description Milestone description
+   * @param daysFromNow Days until milestone due (default: 2 days - SpecWeave AI velocity)
+   */
+  async createOrGetMilestone(
+    title: string,
+    description?: string,
+    daysFromNow: number = 2
+  ): Promise<GitHubMilestone> {
+    // Check if milestone already exists
+    const existing = await this.getMilestoneByTitle(title);
+    if (existing) {
+      return existing;
+    }
+
+    // Calculate due date (SpecWeave default: 1-2 days with AI assistance)
+    const dueDate = new Date();
+    dueDate.setDate(dueDate.getDate() + daysFromNow);
+    const dueDateISO = dueDate.toISOString();
+
+    // Create new milestone with due date
+    const cmd = `gh api repos/${this.repo}/milestones -f title="${title}" ${description ? `-f description="${description}"` : ''} -f due_on="${dueDateISO}" --jq '{number: .number, title: .title, description: .description, state: .state, due_on: .due_on}'`;
+
+    try {
+      const output = execSync(cmd, { encoding: 'utf-8' });
+      return JSON.parse(output);
+    } catch (error: any) {
+      throw new Error(`Failed to create milestone: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get milestone by title
+   */
+  private async getMilestoneByTitle(title: string): Promise<GitHubMilestone | null> {
+    try {
+      const cmd = `gh api repos/${this.repo}/milestones --jq '.[] | select(.title=="${title}") | {number: .number, title: .title, description: .description, state: .state}'`;
+      const output = execSync(cmd, { encoding: 'utf-8' }).trim();
+      return output ? JSON.parse(output) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Create epic issue (increment-level)
+   */
+  async createEpicIssue(
+    title: string,
+    body: string,
+    milestone?: number | string,
+    labels: string[] = []
+  ): Promise<GitHubIssue> {
+    const labelArgs = labels.map(l => `-l "${l}"`).join(' ');
+    const milestoneArg = milestone ? `-m "${milestone}"` : '';
+
+    // Create issue (returns URL)
+    const createCmd = `gh issue create --repo ${this.repo} --title "${this.escapeQuotes(title)}" --body "${this.escapeQuotes(body)}" ${labelArgs} ${milestoneArg}`;
+
+    try {
+      const issueUrl = execSync(createCmd, { encoding: 'utf-8' }).trim();
+
+      // Extract issue number from URL (e.g., https://github.com/owner/repo/issues/123)
+      const issueNumber = parseInt(issueUrl.split('/').pop() || '0', 10);
+
+      if (!issueNumber) {
+        throw new Error('Failed to extract issue number from URL: ' + issueUrl);
+      }
+
+      // Fetch issue details
+      const viewCmd = `gh issue view ${issueNumber} --repo ${this.repo} --json number,title,body,state,url,labels,milestone`;
+      const output = execSync(viewCmd, { encoding: 'utf-8' });
+      const issue = JSON.parse(output);
+
+      return {
+        ...issue,
+        html_url: issue.url,
+        labels: issue.labels?.map((l: any) => l.name) || []
+      };
+    } catch (error: any) {
+      throw new Error(`Failed to create epic issue: ${error.message}`);
+    }
+  }
+
+  /**
+   * Create task issue (linked to epic)
+   */
+  async createTaskIssue(
+    title: string,
+    body: string,
+    epicNumber: number,
+    milestone?: number | string,
+    labels: string[] = []
+  ): Promise<GitHubIssue> {
+    // Add epic reference to body
+    const enhancedBody = `**Part of**: #${epicNumber}\n\n${body}`;
+
+    const labelArgs = labels.map(l => `-l "${l}"`).join(' ');
+    const milestoneArg = milestone ? `-m "${milestone}"` : '';
+
+    // Create issue (returns URL)
+    const createCmd = `gh issue create --repo ${this.repo} --title "${this.escapeQuotes(title)}" --body "${this.escapeQuotes(enhancedBody)}" ${labelArgs} ${milestoneArg}`;
+
+    try {
+      const issueUrl = execSync(createCmd, { encoding: 'utf-8' }).trim();
+
+      // Extract issue number from URL
+      const issueNumber = parseInt(issueUrl.split('/').pop() || '0', 10);
+
+      if (!issueNumber) {
+        throw new Error('Failed to extract issue number from URL: ' + issueUrl);
+      }
+
+      // Fetch issue details
+      const viewCmd = `gh issue view ${issueNumber} --repo ${this.repo} --json number,title,body,state,url,labels,milestone`;
+      const output = execSync(viewCmd, { encoding: 'utf-8' });
+      const issue = JSON.parse(output);
+
+      return {
+        ...issue,
+        html_url: issue.url,
+        labels: issue.labels?.map((l: any) => l.name) || []
+      };
+    } catch (error: any) {
+      throw new Error(`Failed to create task issue: ${error.message}`);
+    }
+  }
+
+  /**
+   * Update issue body
+   */
+  async updateIssueBody(issueNumber: number, newBody: string): Promise<void> {
+    const cmd = `gh issue edit ${issueNumber} --repo ${this.repo} --body "${this.escapeQuotes(newBody)}"`;
+
+    try {
+      execSync(cmd, { encoding: 'utf-8', stdio: 'pipe' });
+    } catch (error: any) {
+      throw new Error(`Failed to update issue #${issueNumber}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Get issue details
+   */
+  async getIssue(issueNumber: number): Promise<GitHubIssue> {
+    const cmd = `gh issue view ${issueNumber} --repo ${this.repo} --json number,title,body,state,html_url,labels,milestone`;
+
+    try {
+      const output = execSync(cmd, { encoding: 'utf-8' });
+      const issue = JSON.parse(output);
+      return {
+        ...issue,
+        labels: issue.labels?.map((l: any) => l.name) || []
+      };
+    } catch (error: any) {
+      throw new Error(`Failed to get issue #${issueNumber}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Close issue
+   */
+  async closeIssue(issueNumber: number, comment?: string): Promise<void> {
+    if (comment) {
+      await this.addComment(issueNumber, comment);
+    }
+
+    const cmd = `gh issue close ${issueNumber} --repo ${this.repo}`;
+
+    try {
+      execSync(cmd, { encoding: 'utf-8', stdio: 'pipe' });
+    } catch (error: any) {
+      throw new Error(`Failed to close issue #${issueNumber}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Add comment to issue
+   */
+  async addComment(issueNumber: number, comment: string): Promise<void> {
+    const cmd = `gh issue comment ${issueNumber} --repo ${this.repo} --body "${this.escapeQuotes(comment)}"`;
+
+    try {
+      execSync(cmd, { encoding: 'utf-8', stdio: 'pipe' });
+    } catch (error: any) {
+      throw new Error(`Failed to add comment to issue #${issueNumber}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Add labels to issue
+   */
+  async addLabels(issueNumber: number, labels: string[]): Promise<void> {
+    if (labels.length === 0) return;
+
+    const labelArgs = labels.map(l => `"${l}"`).join(',');
+    const cmd = `gh issue edit ${issueNumber} --repo ${this.repo} --add-label ${labelArgs}`;
+
+    try {
+      execSync(cmd, { encoding: 'utf-8', stdio: 'pipe' });
+    } catch (error: any) {
+      throw new Error(`Failed to add labels to issue #${issueNumber}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Check rate limit status
+   */
+  async checkRateLimit(): Promise<{ remaining: number; limit: number; reset: Date }> {
+    const cmd = `gh api rate_limit --jq '.rate | {remaining: .remaining, limit: .limit, reset: .reset}'`;
+
+    try {
+      const output = execSync(cmd, { encoding: 'utf-8' });
+      const data = JSON.parse(output);
+      return {
+        ...data,
+        reset: new Date(data.reset * 1000)
+      };
+    } catch (error: any) {
+      throw new Error(`Failed to check rate limit: ${error.message}`);
+    }
+  }
+
+  /**
+   * Escape quotes in strings for shell commands
+   */
+  private escapeQuotes(str: string): string {
+    return str
+      .replace(/\\/g, '\\\\')  // Escape backslashes first
+      .replace(/"/g, '\\"')    // Escape double quotes
+      .replace(/`/g, '\\`')    // Escape backticks
+      .replace(/\$/g, '\\$');  // Escape dollar signs
+  }
+
+  /**
+   * Batch create issues with rate limit handling
+   */
+  async batchCreateIssues(
+    issues: Array<{ title: string; body: string; labels?: string[] }>,
+    milestone?: number | string,
+    epicNumber?: number,
+    options: { batchSize?: number; delayMs?: number } = {}
+  ): Promise<GitHubIssue[]> {
+    const { batchSize = 10, delayMs = 6000 } = options; // 10 issues per minute by default
+    const createdIssues: GitHubIssue[] = [];
+
+    for (let i = 0; i < issues.length; i += batchSize) {
+      const batch = issues.slice(i, i + batchSize);
+
+      console.log(`Creating issues ${i + 1}-${Math.min(i + batchSize, issues.length)} of ${issues.length}...`);
+
+      for (const issue of batch) {
+        try {
+          const created = epicNumber
+            ? await this.createTaskIssue(issue.title, issue.body, epicNumber, milestone, issue.labels)
+            : await this.createEpicIssue(issue.title, issue.body, milestone, issue.labels);
+
+          createdIssues.push(created);
+        } catch (error: any) {
+          console.error(`Failed to create issue "${issue.title}":`, error.message);
+        }
+      }
+
+      // Delay between batches (except after last batch)
+      if (i + batchSize < issues.length) {
+        console.log(`Waiting ${delayMs / 1000}s to avoid rate limits...`);
+        await this.sleep(delayMs);
+      }
+    }
+
+    return createdIssues;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}

package/plugins/specweave-github/lib/index.ts

@@ -0,0 +1,10 @@
+/**
+ * SpecWeave GitHub Plugin - Library Entry Point
+ * Task-level GitHub synchronization
+ */
+
+export { GitHubClient } from './github-client';
+export { TaskParser } from './task-parser';
+export { TaskSync } from './task-sync';
+export { SubtaskSync } from './subtask-sync';
+export * from './types';

package/plugins/specweave-github/lib/subtask-sync.ts

@@ -0,0 +1,225 @@
+/**
+ * Subtask synchronization with GitHub issue checkboxes
+ * Updates GitHub issue body when subtasks complete
+ */
+
+import { GitHubClient } from './github-client';
+import { TaskParser } from './task-parser';
+import { Task, Subtask } from './types';
+import * as path from 'path';
+
+export class SubtaskSync {
+  private client: GitHubClient;
+  private incrementPath: string;
+
+  constructor(incrementPath: string, repo?: string) {
+    this.incrementPath = incrementPath;
+    this.client = new GitHubClient(repo);
+  }
+
+  /**
+   * Update subtask status in GitHub issue
+   */
+  async updateSubtaskStatus(
+    taskId: string,
+    subtaskId: string,
+    completed: boolean
+  ): Promise<void> {
+    // 1. Parse tasks to get task info
+    const tasks = TaskParser.parseTasksFile(this.incrementPath);
+    const task = tasks.find(t => t.id === taskId);
+
+    if (!task) {
+      throw new Error(`Task ${taskId} not found`);
+    }
+
+    if (!task.githubIssue) {
+      console.warn(`Task ${taskId} not synced to GitHub. Skipping subtask sync.`);
+      return;
+    }
+
+    // 2. Get current issue
+    const issue = await this.client.getIssue(task.githubIssue);
+
+    // 3. Update subtask checkbox in issue body
+    const updatedBody = this.updateSubtaskCheckbox(
+      issue.body,
+      subtaskId,
+      completed
+    );
+
+    // 4. Update GitHub issue
+    await this.client.updateIssueBody(task.githubIssue, updatedBody);
+
+    // 5. Check if all subtasks done
+    const allDone = this.areAllSubtasksDone(updatedBody);
+    if (allDone) {
+      await this.client.addComment(
+        task.githubIssue,
+        '✅ All subtasks completed!'
+      );
+    }
+
+    console.log(`✅ Updated subtask ${subtaskId} in GitHub issue #${task.githubIssue}`);
+  }
+
+  /**
+   * Sync all subtasks for a task
+   */
+  async syncAllSubtasks(taskId: string): Promise<void> {
+    const tasks = TaskParser.parseTasksFile(this.incrementPath);
+    const task = tasks.find(t => t.id === taskId);
+
+    if (!task || !task.githubIssue || !task.subtasks) {
+      return;
+    }
+
+    const issue = await this.client.getIssue(task.githubIssue);
+    let updatedBody = issue.body;
+
+    // Update all subtasks
+    for (const subtask of task.subtasks) {
+      updatedBody = this.updateSubtaskCheckbox(
+        updatedBody,
+        subtask.id,
+        subtask.completed
+      );
+    }
+
+    await this.client.updateIssueBody(task.githubIssue, updatedBody);
+    console.log(`✅ Synced all subtasks for ${taskId} to GitHub issue #${task.githubIssue}`);
+  }
+
+  /**
+   * Update checkbox in issue body
+   */
+  private updateSubtaskCheckbox(
+    body: string,
+    subtaskId: string,
+    completed: boolean
+  ): string {
+    const checkbox = completed ? '[x]' : '[ ]';
+
+    // Try to find by subtask ID
+    const idPattern = new RegExp(`^(- \\[[ x]\\]\\s+${this.escapeRegex(subtaskId)}:.+)$`, 'm');
+    if (idPattern.test(body)) {
+      return body.replace(idPattern, (match) => {
+        return match.replace(/\[[ x]\]/, checkbox);
+      });
+    }
+
+    // Fallback: try to find by description (less reliable)
+    // This is a basic approach - could be enhanced
+    return body;
+  }
+
+  /**
+   * Check if all subtasks are done
+   */
+  private areAllSubtasksDone(body: string): boolean {
+    const subtaskLines = body.match(/^- \[[ x]\] S-\d+-\d+:.+$/gm);
+    if (!subtaskLines || subtaskLines.length === 0) {
+      return false;
+    }
+
+    return subtaskLines.every(line => line.includes('[x]'));
+  }
+
+  /**
+   * Escape special regex characters
+   */
+  private escapeRegex(str: string): string {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+
+  /**
+   * Post task completion comment to GitHub issue
+   */
+  async postTaskCompletionComment(
+    taskId: string,
+    stats: {
+      filesModified?: number;
+      linesAdded?: number;
+      linesDeleted?: number;
+      testsAdded?: number;
+      actualDuration?: string;
+      estimatedDuration?: string;
+      summary?: string;
+      nextTask?: string;
+      progress?: { completed: number; total: number };
+    }
+  ): Promise<void> {
+    const tasks = TaskParser.parseTasksFile(this.incrementPath);
+    const task = tasks.find(t => t.id === taskId);
+
+    if (!task || !task.githubIssue) {
+      return;
+    }
+
+    const {
+      filesModified = 0,
+      linesAdded = 0,
+      linesDeleted = 0,
+      testsAdded = 0,
+      actualDuration = 'Unknown',
+      estimatedDuration = task.estimate,
+      summary = 'No summary provided',
+      nextTask = 'None',
+      progress
+    } = stats;
+
+    const comment = `✅ **Task Completed**
+
+**Files Modified**: ${filesModified} files (+${linesAdded}/-${linesDeleted} lines)
+**Tests**: ${testsAdded > 0 ? `All passing (${testsAdded} new tests)` : 'All passing'}
+**Duration**: ${actualDuration} (estimated: ${estimatedDuration})
+
+**What Changed**:
+${summary}
+
+**Next Task**: ${nextTask}
+
+---
+${progress ? `Progress: ${progress.completed}/${progress.total} tasks (${Math.round(progress.completed / progress.total * 100)}%)` : ''}
+🤖 Posted by SpecWeave`;
+
+    await this.client.addComment(task.githubIssue, comment);
+    console.log(`✅ Posted completion comment to issue #${task.githubIssue}`);
+  }
+
+  /**
+   * Update epic issue progress
+   */
+  async updateEpicProgress(epicIssueNumber: number, completed: number, total: number): Promise<void> {
+    const epic = await this.client.getIssue(epicIssueNumber);
+
+    // Update checkboxes in epic body
+    const tasks = TaskParser.parseTasksFile(this.incrementPath);
+    let updatedBody = epic.body;
+
+    for (const task of tasks) {
+      if (task.status === 'completed') {
+        // Find and check the checkbox for this task
+        const taskPattern = new RegExp(`^(- \\[[ x]\\] \\[${this.escapeRegex(task.id)}\\].+)$`, 'm');
+        if (taskPattern.test(updatedBody)) {
+          updatedBody = updatedBody.replace(taskPattern, (match) => {
+            return match.replace(/\[[ x]\]/, '[x]');
+          });
+        }
+      }
+    }
+
+    await this.client.updateIssueBody(epicIssueNumber, updatedBody);
+
+    // Post progress comment
+    const progressComment = `📊 **Progress Update**
+
+${completed}/${total} tasks completed (${Math.round(completed / total * 100)}%)
+
+---
+🤖 Updated by SpecWeave`;
+
+    await this.client.addComment(epicIssueNumber, progressComment);
+    console.log(`✅ Updated epic issue #${epicIssueNumber} progress`);
+  }
+}