specweave 0.12.1 → 0.12.3

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

@@ -0,0 +1,656 @@
+/**
+ * GitHub Spec Sync
+ *
+ * CORRECT ARCHITECTURE:
+ * - Syncs .specweave/docs/internal/specs/spec-*.md ↔ GitHub Projects
+ * - NOT increments ↔ GitHub Issues (that was wrong!)
+ *
+ * Mapping:
+ * - Spec → GitHub Project
+ * - User Story → GitHub Project Card/Issue
+ * - Acceptance Criteria → Checklist in Issue
+ *
+ * @module github-spec-sync
+ */
+
+import { SpecMetadataManager } from '../../../src/core/specs/spec-metadata-manager.js';
+import { SpecParser } from '../../../src/core/specs/spec-parser.js';
+import {
+  SpecContent,
+  UserStory,
+  SpecSyncResult,
+  SpecSyncConflict
+} from '../../../src/core/types/spec-metadata.js';
+import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
+
+export interface GitHubProject {
+  id: number;
+  title: string;
+  number: number;
+  url: string;
+  state: 'open' | 'closed';
+  owner: string;
+  repo: string;
+}
+
+export interface GitHubProjectCard {
+  id: number;
+  note?: string;
+  state: string;
+  column_id: number;
+  content_url?: string; // Link to issue if card is linked
+}
+
+export interface GitHubIssue {
+  number: number;
+  title: string;
+  body: string;
+  state: 'open' | 'closed';
+  labels: string[];
+  assignees: string[];
+}
+
+export class GitHubSpecSync {
+  private specManager: SpecMetadataManager;
+
+  constructor(projectRoot: string = process.cwd()) {
+    this.specManager = new SpecMetadataManager(projectRoot);
+  }
+
+  /**
+   * Sync spec to GitHub Project (CREATE or UPDATE)
+   */
+  async syncSpecToGitHub(specId: string): Promise<SpecSyncResult> {
+    console.log(`\n🔄 Syncing spec ${specId} to GitHub Project...`);
+
+    try {
+      // 1. Load spec
+      const spec = await this.specManager.loadSpec(specId);
+      if (!spec) {
+        return {
+          success: false,
+          specId,
+          provider: 'github',
+          error: `Spec ${specId} not found`
+        };
+      }
+
+      // 2. Detect repository
+      const repoInfo = await this.detectRepo();
+      if (!repoInfo) {
+        return {
+          success: false,
+          specId,
+          provider: 'github',
+          error: 'Could not detect GitHub repository'
+        };
+      }
+
+      const { owner, repo } = repoInfo;
+
+      // 3. Check if spec already linked to GitHub Project
+      const existingLink = spec.metadata.externalLinks?.github;
+
+      let project: GitHubProject;
+
+      if (existingLink?.projectId) {
+        // UPDATE existing project
+        console.log(`   Found existing GitHub Project #${existingLink.projectId}`);
+        project = await this.updateGitHubProject(
+          owner,
+          repo,
+          existingLink.projectId,
+          spec
+        );
+      } else {
+        // CREATE new project
+        console.log('   Creating new GitHub Project...');
+        project = await this.createGitHubProject(owner, repo, spec);
+
+        // Link spec to project
+        await this.specManager.linkToExternal(specId, 'github', {
+          id: project.id,
+          url: project.url,
+          owner,
+          repo
+        });
+      }
+
+      // 4. Sync user stories as issues/cards
+      const changes = await this.syncUserStories(owner, repo, project.number, spec);
+
+      console.log('✅ Sync complete!');
+
+      return {
+        success: true,
+        specId,
+        provider: 'github',
+        externalId: project.id.toString(),
+        url: project.url,
+        changes
+      };
+
+    } catch (error) {
+      console.error('❌ Error syncing to GitHub:', error);
+      return {
+        success: false,
+        specId,
+        provider: 'github',
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  /**
+   * Sync FROM GitHub Project to spec (bidirectional)
+   */
+  async syncFromGitHub(specId: string): Promise<SpecSyncResult> {
+    console.log(`\n🔄 Syncing FROM GitHub to spec ${specId}...`);
+
+    try {
+      // 1. Load spec
+      const spec = await this.specManager.loadSpec(specId);
+      if (!spec) {
+        return {
+          success: false,
+          specId,
+          provider: 'github',
+          error: `Spec ${specId} not found`
+        };
+      }
+
+      // 2. Get GitHub Project link
+      const githubLink = spec.metadata.externalLinks?.github;
+      if (!githubLink?.projectId) {
+        return {
+          success: false,
+          specId,
+          provider: 'github',
+          error: 'Spec not linked to GitHub Project'
+        };
+      }
+
+      const { owner, repo } = await this.detectRepo() || { owner: '', repo: '' };
+
+      // 3. Fetch GitHub Project state
+      const project = await this.fetchGitHubProject(owner, repo, githubLink.projectId);
+
+      // 4. Detect conflicts
+      const conflicts = await this.detectConflicts(spec, project);
+
+      if (conflicts.length === 0) {
+        console.log('✅ No conflicts - spec and GitHub in sync');
+        return {
+          success: true,
+          specId,
+          provider: 'github',
+          externalId: project.id.toString(),
+          url: project.url
+        };
+      }
+
+      console.log(`⚠️  Detected ${conflicts.length} conflict(s)`);
+
+      // 5. Resolve conflicts (GitHub wins by default for now)
+      await this.resolveConflicts(spec, conflicts);
+
+      console.log('✅ Sync FROM GitHub complete!');
+
+      return {
+        success: true,
+        specId,
+        provider: 'github',
+        externalId: project.id.toString(),
+        url: project.url,
+        conflicts
+      };
+
+    } catch (error) {
+      console.error('❌ Error syncing FROM GitHub:', error);
+      return {
+        success: false,
+        specId,
+        provider: 'github',
+        error: error instanceof Error ? error.message : 'Unknown error'
+      };
+    }
+  }
+
+  /**
+   * Create new GitHub Project for spec
+   */
+  private async createGitHubProject(
+    owner: string,
+    repo: string,
+    spec: SpecContent
+  ): Promise<GitHubProject> {
+    const projectTitle = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    const projectBody = this.generateProjectDescription(spec);
+
+    // Use GraphQL to create project
+    const query = `
+      mutation CreateProject($ownerId: ID!, $title: String!, $body: String!) {
+        createProjectV2(input: {
+          ownerId: $ownerId,
+          title: $title,
+          body: $body
+        }) {
+          projectV2 {
+            id
+            title
+            number
+            url
+          }
+        }
+      }
+    `;
+
+    // Get owner ID first
+    const ownerId = await this.getOwnerId(owner);
+
+    const result = await this.executeGraphQL(query, {
+      ownerId,
+      title: projectTitle,
+      body: projectBody
+    });
+
+    const project = result.data.createProjectV2.projectV2;
+
+    console.log(`   ✅ Created GitHub Project #${project.number}: ${project.url}`);
+
+    return {
+      id: parseInt(project.id, 10),
+      title: project.title,
+      number: project.number,
+      url: project.url,
+      state: 'open',
+      owner,
+      repo
+    };
+  }
+
+  /**
+   * Update existing GitHub Project
+   */
+  private async updateGitHubProject(
+    owner: string,
+    repo: string,
+    projectId: number,
+    spec: SpecContent
+  ): Promise<GitHubProject> {
+    const projectTitle = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    const projectBody = this.generateProjectDescription(spec);
+
+    // Use GraphQL to update project
+    const query = `
+      mutation UpdateProject($projectId: ID!, $title: String, $body: String) {
+        updateProjectV2(input: {
+          projectId: $projectId,
+          title: $title,
+          body: $body
+        }) {
+          projectV2 {
+            id
+            title
+            number
+            url
+          }
+        }
+      }
+    `;
+
+    const result = await this.executeGraphQL(query, {
+      projectId: projectId.toString(),
+      title: projectTitle,
+      body: projectBody
+    });
+
+    const project = result.data.updateProjectV2.projectV2;
+
+    console.log(`   ✅ Updated GitHub Project #${project.number}`);
+
+    return {
+      id: projectId,
+      title: project.title,
+      number: project.number,
+      url: project.url,
+      state: 'open',
+      owner,
+      repo
+    };
+  }
+
+  /**
+   * Sync user stories as GitHub Issues
+   */
+  private async syncUserStories(
+    owner: string,
+    repo: string,
+    projectNumber: number,
+    spec: SpecContent
+  ): Promise<{ created: string[]; updated: string[]; deleted: string[] }> {
+    const created: string[] = [];
+    const updated: string[] = [];
+    const deleted: string[] = [];
+
+    if (!spec.metadata.userStories || spec.metadata.userStories.length === 0) {
+      console.log('   ℹ️  No user stories to sync');
+      return { created, updated, deleted };
+    }
+
+    console.log(`   Syncing ${spec.metadata.userStories.length} user stories...`);
+
+    for (const us of spec.metadata.userStories) {
+      // Create or update issue for each user story
+      const issueTitle = `[${us.id}] ${us.title}`;
+      const issueBody = this.generateIssueBody(us);
+
+      // Check if issue already exists (by title pattern)
+      const existingIssue = await this.findIssueByTitle(owner, repo, us.id);
+
+      if (existingIssue) {
+        // UPDATE existing issue
+        await this.updateIssue(owner, repo, existingIssue.number, {
+          title: issueTitle,
+          body: issueBody,
+          state: us.status === 'done' ? 'closed' : 'open'
+        });
+
+        updated.push(us.id);
+        console.log(`   ✅ Updated ${us.id}`);
+      } else {
+        // CREATE new issue
+        const newIssue = await this.createIssue(owner, repo, {
+          title: issueTitle,
+          body: issueBody,
+          labels: ['user-story', `spec:${spec.metadata.id}`, `priority:${us.priority}`]
+        });
+
+        created.push(us.id);
+        console.log(`   ✅ Created ${us.id} → Issue #${newIssue.number}`);
+      }
+    }
+
+    return { created, updated, deleted };
+  }
+
+  /**
+   * Generate project description from spec
+   */
+  private generateProjectDescription(spec: SpecContent): string {
+    const progress = spec.metadata.progress;
+    const progressText = progress
+      ? `**Progress**: ${progress.percentComplete}% (${progress.completedUserStories}/${progress.totalUserStories} user stories)`
+      : '**Progress**: N/A';
+
+    return `
+# ${spec.metadata.title}
+
+**Spec ID**: ${spec.metadata.id}
+**Priority**: ${spec.metadata.priority}
+**Status**: ${spec.metadata.status}
+${progressText}
+
+---
+
+${SpecParser.extractOverview(spec.markdown)}
+
+---
+
+## User Stories
+
+${spec.metadata.userStories?.length || 0} user stories tracked in this project.
+
+---
+
+🤖 **Auto-synced from SpecWeave**
+Last updated: ${new Date().toISOString()}
+`.trim();
+  }
+
+  /**
+   * Generate issue body from user story
+   */
+  private generateIssueBody(us: UserStory): string {
+    const acList = us.acceptanceCriteria
+      .map(ac => `- [${ac.status === 'done' ? 'x' : ' '}] ${ac.description}`)
+      .join('\n');
+
+    return `
+## User Story
+
+${us.title}
+
+## Acceptance Criteria
+
+${acList}
+
+---
+
+**Priority**: ${us.priority}
+**Status**: ${us.status}
+
+🤖 **Auto-synced from SpecWeave**
+`.trim();
+  }
+
+  /**
+   * Detect conflicts between spec and GitHub
+   */
+  private async detectConflicts(
+    spec: SpecContent,
+    project: GitHubProject
+  ): Promise<SpecSyncConflict[]> {
+    const conflicts: SpecSyncConflict[] = [];
+
+    // Compare project title
+    const expectedTitle = `[${spec.metadata.id.toUpperCase()}] ${spec.metadata.title}`;
+    if (project.title !== expectedTitle) {
+      conflicts.push({
+        type: 'metadata',
+        field: 'title',
+        localValue: spec.metadata.title,
+        remoteValue: project.title,
+        resolution: 'remote-wins',
+        description: 'Project title differs from spec title'
+      });
+    }
+
+    // TODO: Compare user stories and their statuses
+
+    return conflicts;
+  }
+
+  /**
+   * Resolve conflicts
+   */
+  private async resolveConflicts(
+    spec: SpecContent,
+    conflicts: SpecSyncConflict[]
+  ): Promise<void> {
+    for (const conflict of conflicts) {
+      if (conflict.resolution === 'remote-wins') {
+        console.log(`   🔄 Resolving: ${conflict.description} (GitHub wins)`);
+        // Update spec metadata from GitHub
+        if (conflict.field === 'title') {
+          await this.specManager.saveMetadata(spec.metadata.id, {
+            title: conflict.remoteValue
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Execute GraphQL query against GitHub API
+   */
+  private async executeGraphQL(query: string, variables: any): Promise<any> {
+    const result = await execFileNoThrow('gh', [
+      'api',
+      'graphql',
+      '-f',
+      `query=${query}`,
+      ...Object.entries(variables).flatMap(([key, value]) => ['-F', `${key}=${value}`])
+    ]);
+
+    if (result.error) {
+      throw new Error(`GraphQL query failed: ${result.error}`);
+    }
+
+    return JSON.parse(result.stdout);
+  }
+
+  /**
+   * Get owner ID (user or organization)
+   */
+  private async getOwnerId(owner: string): Promise<string> {
+    const query = `
+      query GetOwner($login: String!) {
+        repositoryOwner(login: $login) {
+          id
+        }
+      }
+    `;
+
+    const result = await this.executeGraphQL(query, { login: owner });
+    return result.data.repositoryOwner.id;
+  }
+
+  /**
+   * Fetch GitHub Project details
+   */
+  private async fetchGitHubProject(
+    owner: string,
+    repo: string,
+    projectId: number
+  ): Promise<GitHubProject> {
+    // Placeholder - would use GraphQL to fetch project
+    return {
+      id: projectId,
+      title: 'Project Title',
+      number: 1,
+      url: 'https://github.com/...',
+      state: 'open',
+      owner,
+      repo
+    };
+  }
+
+  /**
+   * Find issue by title pattern
+   */
+  private async findIssueByTitle(
+    owner: string,
+    repo: string,
+    usId: string
+  ): Promise<GitHubIssue | null> {
+    const result = await execFileNoThrow('gh', [
+      'issue',
+      'list',
+      '--repo',
+      `${owner}/${repo}`,
+      '--search',
+      `"[${usId}]" in:title`,
+      '--json',
+      'number,title,body,state,labels',
+      '--limit',
+      '1'
+    ]);
+
+    if (result.error || !result.stdout) {
+      return null;
+    }
+
+    const issues = JSON.parse(result.stdout);
+    return issues.length > 0 ? issues[0] : null;
+  }
+
+  /**
+   * Create GitHub issue
+   */
+  private async createIssue(
+    owner: string,
+    repo: string,
+    issue: { title: string; body: string; labels: string[] }
+  ): Promise<GitHubIssue> {
+    const result = await execFileNoThrow('gh', [
+      'issue',
+      'create',
+      '--repo',
+      `${owner}/${repo}`,
+      '--title',
+      issue.title,
+      '--body',
+      issue.body,
+      '--label',
+      issue.labels.join(','),
+      '--json',
+      'number,title,body,state'
+    ]);
+
+    if (result.error) {
+      throw new Error(`Failed to create issue: ${result.error}`);
+    }
+
+    return JSON.parse(result.stdout);
+  }
+
+  /**
+   * Update GitHub issue
+   */
+  private async updateIssue(
+    owner: string,
+    repo: string,
+    issueNumber: number,
+    updates: { title?: string; body?: string; state?: 'open' | 'closed' }
+  ): Promise<void> {
+    const args = ['issue', 'edit', issueNumber.toString(), '--repo', `${owner}/${repo}`];
+
+    if (updates.title) {
+      args.push('--title', updates.title);
+    }
+
+    if (updates.body) {
+      args.push('--body', updates.body);
+    }
+
+    if (updates.state === 'closed') {
+      args.push('--state', 'closed');
+    } else if (updates.state === 'open') {
+      args.push('--state', 'open');
+    }
+
+    const result = await execFileNoThrow('gh', args);
+
+    if (result.error) {
+      throw new Error(`Failed to update issue #${issueNumber}: ${result.error}`);
+    }
+  }
+
+  /**
+   * Detect GitHub repository from git remote
+   */
+  private async detectRepo(): Promise<{ owner: string; repo: string } | null> {
+    const result = await execFileNoThrow('git', ['remote', 'get-url', 'origin']);
+
+    if (result.error || !result.stdout) {
+      return null;
+    }
+
+    const remoteUrl = result.stdout.trim();
+
+    // Parse GitHub URL
+    // Examples:
+    // - https://github.com/owner/repo.git
+    // - git@github.com:owner/repo.git
+    const httpsMatch = remoteUrl.match(/github\.com[/:]([\w-]+)\/([\w-]+?)(\.git)?$/);
+    if (httpsMatch) {
+      return {
+        owner: httpsMatch[1],
+        repo: httpsMatch[2]
+      };
+    }
+
+    return null;
+  }
+}

package/plugins/specweave-github/skills/github-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: github-sync
-description: Bidirectional synchronization between SpecWeave increments and GitHub Issues (two-way sync by default). Creates issues from increments, tracks progress via comments, updates increment status from issue state, syncs changes in both directions automatically. Activates for GitHub sync, issue creation, increment tracking, GitHub integration, issue management, sync to GitHub, bidirectional sync.
+description: Bidirectional synchronization between SpecWeave increments and GitHub Issues (two-way sync by default). Activates ONLY when user asks questions about GitHub integration or needs help configuring GitHub sync. Does NOT activate for slash commands. For syncing, use /specweave-github:sync command instead.
 ---
 
 # GitHub Sync - Bidirectional Increment ↔ Issue Synchronization
@@ -9,14 +9,22 @@ description: Bidirectional synchronization between SpecWeave increments and GitH
 
 **Default Behavior**: **Bidirectional (two-way) sync** - Changes in either system are automatically synchronized
 
-**When to Use**:
-- Creating new increments (auto-create GitHub issue)
-- Syncing increment progress to GitHub (comments with task completion %)
-- Closing increments (auto-close GitHub issue)
-- Importing GitHub issues as increments
-- Manual sync operations
+**⚠️ IMPORTANT**: This skill provides HELP and GUIDANCE about GitHub sync. For actual syncing, users should use the `/specweave-github:sync` command directly. This skill should NOT auto-activate when the command is being invoked.
 
-**Integration**: Works with `/specweave:github:sync` command
+## When to Activate
+
+✅ **Do activate when**:
+- User asks: "How do I set up GitHub sync?"
+- User asks: "What GitHub credentials do I need?"
+- User asks: "How does the GitHub integration work?"
+- User needs help configuring GitHub integration
+
+❌ **Do NOT activate when**:
+- User invokes `/specweave-github:sync` command (command handles it)
+- Command is already running (avoid duplicate invocation)
+- Task completion hook is syncing (automatic process)
+
+**Integration**: Works with `/specweave-github:sync` command
 
 ---