specweave 0.17.0 → 0.17.2

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

@@ -1,12 +1,61 @@
 import { SpecMetadataManager } from "../../../src/core/specs/spec-metadata-manager.js";
 import { SpecParser } from "../../../src/core/specs/spec-parser.js";
 import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
+import { ProjectContextManager } from "../../../src/core/sync/project-context.js";
 class GitHubSpecSync {
   constructor(projectRoot = process.cwd()) {
+    this.projectRoot = projectRoot;
     this.specManager = new SpecMetadataManager(projectRoot);
+    this.projectContextManager = new ProjectContextManager(projectRoot);
+  }
+  /**
+   * Detect project from spec file path
+   *
+   * Spec path format: .specweave/docs/internal/specs/{project-id}/spec-*.md
+   * OR (single project): .specweave/docs/internal/specs/spec-*.md
+   */
+  async detectProjectFromSpecPath(specFilePath) {
+    const specPathMatch = specFilePath.match(/\.specweave\/docs\/internal\/specs\/([^/]+)\//);
+    if (specPathMatch) {
+      const projectId = specPathMatch[1];
+      const project = await this.projectContextManager.getProject(projectId);
+      return project ? projectId : null;
+    }
+    return "default";
+  }
+  /**
+   * Get GitHub configuration for a project
+   */
+  async getGitHubConfigForProject(projectId) {
+    const config = await this.projectContextManager.load();
+    const project = await this.projectContextManager.getProject(projectId);
+    if (!project) {
+      return null;
+    }
+    const profileId = project.defaultSyncProfile || config.activeProfile;
+    if (!profileId) {
+      return null;
+    }
+    const profile = config.profiles?.[profileId];
+    if (!profile || profile.provider !== "github") {
+      return null;
+    }
+    const githubConfig = profile.config;
+    return {
+      projectId,
+      strategy: githubConfig.githubStrategy || "project-per-spec",
+      owner: githubConfig.owner || "",
+      repo: githubConfig.repo || githubConfig.repos && githubConfig.repos[0] || "",
+      teamBoardId: githubConfig.teamBoardId
+    };
   }
   /**
    * Sync spec to GitHub Project (CREATE or UPDATE)
+   *
+   * MULTI-PROJECT ARCHITECTURE:
+   * - Detects which project the spec belongs to
+   * - Routes to correct GitHub repo based on project config
+   * - Supports multiple sync strategies
    */
   async syncSpecToGitHub(specId) {
     console.log(`
@@ -21,16 +70,71 @@ class GitHubSpecSync {
           error: `Spec ${specId} not found`
         };
       }
-      const repoInfo = await this.detectRepo();
-      if (!repoInfo) {
+      const projectId = await this.detectProjectFromSpecPath(spec.filePath);
+      if (!projectId) {
         return {
           success: false,
           specId,
           provider: "github",
-          error: "Could not detect GitHub repository"
+          error: "Could not determine project for spec"
         };
       }
-      const { owner, repo } = repoInfo;
+      console.log(`   \u{1F4E6} Detected project: ${projectId}`);
+      const githubConfig = await this.getGitHubConfigForProject(projectId);
+      if (!githubConfig) {
+        const repoInfo = await this.detectRepo();
+        if (!repoInfo) {
+          return {
+            success: false,
+            specId,
+            provider: "github",
+            error: `No GitHub configuration found for project '${projectId}'`
+          };
+        }
+        githubConfig.owner = repoInfo.owner;
+        githubConfig.repo = repoInfo.repo;
+        githubConfig.strategy = "project-per-spec";
+      }
+      console.log(`   \u{1F3AF} Strategy: ${githubConfig.strategy}`);
+      console.log(`   \u{1F517} Repository: ${githubConfig.owner}/${githubConfig.repo}`);
+      const { owner, repo, strategy } = githubConfig;
+      return await this.syncWithStrategy(spec, owner, repo, strategy, githubConfig);
+    } catch (error) {
+      console.error("\u274C Error syncing to GitHub:", error);
+      return {
+        success: false,
+        specId,
+        provider: "github",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  /**
+   * Sync spec using specified strategy
+   */
+  async syncWithStrategy(spec, owner, repo, strategy, config) {
+    const specId = spec.metadata.id;
+    switch (strategy) {
+      case "project-per-spec":
+        return await this.syncProjectPerSpec(spec, owner, repo);
+      case "team-board":
+        return await this.syncTeamBoard(spec, owner, repo, config.teamBoardId);
+      case "centralized":
+        return await this.syncCentralized(spec, owner, repo);
+      case "distributed":
+        return await this.syncDistributed(spec, config);
+      default:
+        return await this.syncProjectPerSpec(spec, owner, repo);
+    }
+  }
+  /**
+   * Strategy 1: Project-per-Spec (DEFAULT)
+   * - One GitHub Project per spec
+   * - Current behavior, no changes needed
+   */
+  async syncProjectPerSpec(spec, owner, repo) {
+    const specId = spec.metadata.id;
+    try {
       const existingLink = spec.metadata.externalLinks?.github;
       let project;
       if (existingLink?.projectId) {
@@ -209,42 +313,6 @@ class GitHubSpecSync {
       repo
     };
   }
-  /**
-   * Sync user stories as GitHub Issues
-   */
-  async syncUserStories(owner, repo, projectNumber, spec) {
-    const created = [];
-    const updated = [];
-    const deleted = [];
-    if (!spec.metadata.userStories || spec.metadata.userStories.length === 0) {
-      console.log("   \u2139\uFE0F  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) {
-      const issueTitle = `[${us.id}] ${us.title}`;
-      const issueBody = this.generateIssueBody(us);
-      const existingIssue = await this.findIssueByTitle(owner, repo, us.id);
-      if (existingIssue) {
-        await this.updateIssue(owner, repo, existingIssue.number, {
-          title: issueTitle,
-          body: issueBody,
-          state: us.status === "done" ? "closed" : "open"
-        });
-        updated.push(us.id);
-        console.log(`   \u2705 Updated ${us.id}`);
-      } else {
-        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(`   \u2705 Created ${us.id} \u2192 Issue #${newIssue.number}`);
-      }
-    }
-    return { created, updated, deleted };
-  }
   /**
    * Generate project description from spec
    */
@@ -440,6 +508,303 @@ ${acList}
       throw new Error(`Failed to update issue #${issueNumber}: ${result.error}`);
     }
   }
+  /**
+   * Strategy 2: Team-Board
+   * - One GitHub Project per team (aggregates multiple specs)
+   * - All specs from the same team/project sync to same board
+   */
+  async syncTeamBoard(spec, owner, repo, teamBoardId) {
+    const specId = spec.metadata.id;
+    try {
+      console.log("   \u{1F4CB} Using team-board strategy (aggregated)");
+      if (!teamBoardId) {
+        const projectId = await this.detectProjectFromSpecPath(spec.filePath);
+        const project = await this.projectContextManager.getProject(projectId || "default");
+        const teamName = project?.team || "Team";
+        const teamProject = await this.createGitHubProject(owner, repo, {
+          ...spec,
+          metadata: {
+            ...spec.metadata,
+            title: `${teamName} Board`
+          }
+        });
+        teamBoardId = teamProject.id;
+        console.log(`   \u2705 Created team board: ${teamName} Board (#${teamBoardId})`);
+      }
+      const changes = await this.syncUserStories(owner, repo, teamBoardId, spec);
+      return {
+        success: true,
+        specId,
+        provider: "github",
+        externalId: teamBoardId.toString(),
+        url: `https://github.com/orgs/${owner}/projects/${teamBoardId}`,
+        changes
+      };
+    } catch (error) {
+      console.error("\u274C Error syncing to team board:", error);
+      return {
+        success: false,
+        specId,
+        provider: "github",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  /**
+   * Strategy 3: Centralized
+   * - Parent repo tracks all specs (multi-repo pattern)
+   * - Issues created in parent repo with tags for child repos
+   */
+  async syncCentralized(spec, parentOwner, parentRepo) {
+    const specId = spec.metadata.id;
+    try {
+      console.log("   \u{1F3E2} Using centralized strategy (parent repo tracks all)");
+      const project = await this.createGitHubProject(parentOwner, parentRepo, spec);
+      const projectId = await this.detectProjectFromSpecPath(spec.filePath);
+      const projectContext = await this.projectContextManager.getProject(projectId || "default");
+      const changes = await this.syncUserStories(
+        parentOwner,
+        parentRepo,
+        project.number,
+        spec,
+        projectContext?.name ? [`project:${projectContext.name}`] : []
+      );
+      console.log(`   \u2705 Synced to parent repo: ${parentOwner}/${parentRepo}`);
+      return {
+        success: true,
+        specId,
+        provider: "github",
+        externalId: project.id.toString(),
+        url: project.url,
+        changes
+      };
+    } catch (error) {
+      console.error("\u274C Error syncing centralized:", error);
+      return {
+        success: false,
+        specId,
+        provider: "github",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  /**
+   * Strategy 4: Distributed
+   * - Each team syncs to their repo (microservices)
+   * - Cross-team specs create issues in multiple repos
+   */
+  async syncDistributed(spec, config) {
+    const specId = spec.metadata.id;
+    try {
+      console.log("   \u{1F310} Using distributed strategy (per-team repos)");
+      const projectId = config.projectId;
+      const projectContext = await this.projectContextManager.getProject(projectId);
+      if (!projectContext) {
+        throw new Error(`Project context not found for ${projectId}`);
+      }
+      const isCrossTeam = this.isCrossTeamSpec(spec);
+      if (isCrossTeam) {
+        console.log("   \u{1F517} Cross-team spec detected, syncing to multiple repos");
+        return await this.syncCrossTeamSpec(spec, projectId);
+      }
+      return await this.syncProjectPerSpec(spec, config.owner, config.repo);
+    } catch (error) {
+      console.error("\u274C Error syncing distributed:", error);
+      return {
+        success: false,
+        specId,
+        provider: "github",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  /**
+   * Check if spec is cross-team (touches multiple projects)
+   *
+   * Detection heuristics:
+   * - Spec title contains keywords like "integration", "cross-team", "shared"
+   * - User stories reference multiple projects/teams
+   * - Tags include multiple project names
+   */
+  isCrossTeamSpec(spec) {
+    const crossTeamKeywords = [
+      "integration",
+      "cross-team",
+      "cross-project",
+      "shared",
+      "common",
+      "auth",
+      // Auth often touches frontend + backend
+      "api-contract",
+      "sync"
+    ];
+    const title = spec.metadata.title.toLowerCase();
+    const hasCrossTeamKeyword = crossTeamKeywords.some(
+      (keyword) => title.includes(keyword)
+    );
+    const tags = spec.metadata.tags || [];
+    const projectTags = tags.filter((tag) => tag.startsWith("project:"));
+    const hasMultipleProjects = projectTags.length > 1;
+    return hasCrossTeamKeyword || hasMultipleProjects;
+  }
+  /**
+   * Sync cross-team spec to multiple repositories
+   *
+   * Creates issues in multiple repos:
+   * - Frontend repo gets frontend-specific user stories
+   * - Backend repo gets backend-specific user stories
+   * - Shared stories get created in both with cross-links
+   */
+  async syncCrossTeamSpec(spec, projectId) {
+    const specId = spec.metadata.id;
+    try {
+      const config = await this.projectContextManager.load();
+      const relatedProfiles = await this.detectRelatedProfiles(spec, config);
+      if (relatedProfiles.length === 0) {
+        throw new Error("No related profiles found for cross-team spec");
+      }
+      console.log(`   \u{1F4C2} Syncing to ${relatedProfiles.length} repositories:`);
+      const allChanges = {
+        created: [],
+        updated: [],
+        deleted: []
+      };
+      for (const profile of relatedProfiles) {
+        const githubConfig = profile.config;
+        console.log(`      \u2192 ${githubConfig.owner}/${githubConfig.repo}`);
+        const relevantStories = this.filterRelevantUserStories(
+          spec,
+          profile.projectContext?.name || ""
+        );
+        if (relevantStories.length === 0) {
+          console.log(`        \u2139\uFE0F  No relevant stories, skipping`);
+          continue;
+        }
+        const project = await this.createGitHubProject(
+          githubConfig.owner || "",
+          githubConfig.repo || "",
+          {
+            ...spec,
+            metadata: {
+              ...spec.metadata,
+              userStories: relevantStories
+            }
+          }
+        );
+        const changes = await this.syncUserStories(
+          githubConfig.owner || "",
+          githubConfig.repo || "",
+          project.number,
+          { ...spec, metadata: { ...spec.metadata, userStories: relevantStories } }
+        );
+        allChanges.created.push(...changes.created);
+        allChanges.updated.push(...changes.updated);
+        allChanges.deleted.push(...changes.deleted);
+      }
+      console.log("   \u2705 Cross-team sync complete!");
+      return {
+        success: true,
+        specId,
+        provider: "github",
+        externalId: "cross-team",
+        url: "multiple-repos",
+        changes: allChanges
+      };
+    } catch (error) {
+      console.error("\u274C Error syncing cross-team spec:", error);
+      return {
+        success: false,
+        specId,
+        provider: "github",
+        error: error instanceof Error ? error.message : "Unknown error"
+      };
+    }
+  }
+  /**
+   * Detect related profiles for cross-team spec
+   */
+  async detectRelatedProfiles(spec, config) {
+    const profiles = [];
+    const tags = spec.metadata.tags || [];
+    const projectTags = tags.filter((tag) => tag.startsWith("project:")).map((tag) => tag.replace("project:", ""));
+    for (const projectId of projectTags) {
+      const project = await this.projectContextManager.getProject(projectId);
+      if (project && project.defaultSyncProfile) {
+        const profile = config.profiles?.[project.defaultSyncProfile];
+        if (profile && profile.provider === "github") {
+          profiles.push({
+            ...profile,
+            projectContext: project
+          });
+        }
+      }
+    }
+    return profiles;
+  }
+  /**
+   * Filter user stories relevant to a specific project
+   *
+   * Heuristics:
+   * - Story title/description contains project keywords
+   * - Story tags include project name
+   * - Story implementation references project folder
+   */
+  filterRelevantUserStories(spec, projectName) {
+    if (!spec.metadata.userStories) {
+      return [];
+    }
+    const projectKeywords = projectName.toLowerCase().split(/[-_\s]/);
+    return spec.metadata.userStories.filter((story) => {
+      const storyText = `${story.title} ${story.description || ""}`.toLowerCase();
+      const mentionsProject = projectKeywords.some(
+        (keyword) => storyText.includes(keyword)
+      );
+      const isShared = !storyText.match(/\b(frontend|backend|mobile|infra|platform)\b/);
+      return mentionsProject || isShared;
+    });
+  }
+  /**
+   * Enhanced syncUserStories with optional extra labels
+   */
+  async syncUserStories(owner, repo, projectNumber, spec, extraLabels = []) {
+    const created = [];
+    const updated = [];
+    const deleted = [];
+    if (!spec.metadata.userStories || spec.metadata.userStories.length === 0) {
+      console.log("   \u2139\uFE0F  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) {
+      const issueTitle = `[${us.id}] ${us.title}`;
+      const issueBody = this.generateIssueBody(us);
+      const existingIssue = await this.findIssueByTitle(owner, repo, us.id);
+      const labels = [
+        "user-story",
+        `spec:${spec.metadata.id}`,
+        `priority:${us.priority}`,
+        ...extraLabels
+      ];
+      if (existingIssue) {
+        await this.updateIssue(owner, repo, existingIssue.number, {
+          title: issueTitle,
+          body: issueBody,
+          state: us.status === "done" ? "closed" : "open"
+        });
+        updated.push(us.id);
+        console.log(`   \u2705 Updated ${us.id}`);
+      } else {
+        const newIssue = await this.createIssue(owner, repo, {
+          title: issueTitle,
+          body: issueBody,
+          labels
+        });
+        created.push(us.id);
+        console.log(`   \u2705 Created ${us.id} \u2192 Issue #${newIssue.number}`);
+      }
+    }
+    return { created, updated, deleted };
+  }
   /**
    * Detect GitHub repository from git remote
    */