specweave 1.0.235 → 1.0.239

package/plugins/specweave-github/lib/github-conflict-resolver.ts

@@ -0,0 +1,154 @@
+/**
+ * GitHub Conflict Resolver
+ *
+ * Field-level conflict detection and resolution between spec state
+ * and GitHub issue state. Supports title, status, and AC fields.
+ *
+ * @module github-conflict-resolver
+ */
+
+export type ConflictResolution = 'github-wins' | 'spec-wins' | 'prompt';
+
+export interface ConflictField {
+  field: string;
+  specValue: string;
+  githubValue: string;
+  defaultResolution: ConflictResolution;
+}
+
+export interface ResolvedConflict {
+  field: string;
+  specValue: string;
+  githubValue: string;
+  resolution: ConflictResolution;
+  resolvedValue: string;
+  resolvedAt: string;
+}
+
+export interface ConflictResolverConfig {
+  defaultStatusResolution?: ConflictResolution;
+  defaultContentResolution?: ConflictResolution;
+  defaultACResolution?: ConflictResolution;
+}
+
+interface SpecState {
+  title: string;
+  status: string;
+  acceptanceCriteria: Array<{ id: string; completed: boolean }>;
+}
+
+interface GitHubState {
+  title: string;
+  state: 'open' | 'closed';
+  acceptanceCriteria: Array<{ id: string; completed: boolean }>;
+}
+
+export class GitHubConflictResolver {
+  private statusResolution: ConflictResolution;
+  private contentResolution: ConflictResolution;
+  private acResolution: ConflictResolution;
+
+  constructor(config?: ConflictResolverConfig) {
+    this.statusResolution = config?.defaultStatusResolution ?? 'github-wins';
+    this.contentResolution = config?.defaultContentResolution ?? 'prompt';
+    this.acResolution = config?.defaultACResolution ?? 'github-wins';
+  }
+
+  /**
+   * Detect conflicts between spec and GitHub states.
+   */
+  detectConflicts(specState: SpecState, githubState: GitHubState): ConflictField[] {
+    const conflicts: ConflictField[] = [];
+
+    // Title conflict
+    if (specState.title !== githubState.title) {
+      conflicts.push({
+        field: 'title',
+        specValue: specState.title,
+        githubValue: githubState.title,
+        defaultResolution: this.contentResolution,
+      });
+    }
+
+    // Status conflict: map GitHub state to spec status for comparison
+    const githubStatus = githubState.state; // 'open' or 'closed'
+    const specStatus = specState.status;
+    const statusMismatch = this.isStatusConflict(specStatus, githubStatus);
+
+    if (statusMismatch) {
+      conflicts.push({
+        field: 'status',
+        specValue: specStatus,
+        githubValue: githubStatus,
+        defaultResolution: this.statusResolution,
+      });
+    }
+
+    // AC conflicts
+    const ghAcMap = new Map(
+      githubState.acceptanceCriteria.map(ac => [ac.id, ac.completed]),
+    );
+
+    for (const specAc of specState.acceptanceCriteria) {
+      const ghCompleted = ghAcMap.get(specAc.id);
+      if (ghCompleted !== undefined && specAc.completed !== ghCompleted) {
+        conflicts.push({
+          field: `ac:${specAc.id}`,
+          specValue: String(specAc.completed),
+          githubValue: String(ghCompleted),
+          defaultResolution: this.acResolution,
+        });
+      }
+    }
+
+    return conflicts;
+  }
+
+  /**
+   * Resolve all conflicts using their default resolution strategy.
+   */
+  resolveConflicts(conflicts: ConflictField[]): ResolvedConflict[] {
+    return conflicts.map(c => this.resolveConflict(c));
+  }
+
+  /**
+   * Resolve a single conflict with optional override.
+   */
+  resolveConflict(conflict: ConflictField, resolution?: ConflictResolution): ResolvedConflict {
+    const effectiveResolution = resolution ?? conflict.defaultResolution;
+    let resolvedValue: string;
+
+    switch (effectiveResolution) {
+      case 'github-wins':
+        resolvedValue = conflict.githubValue;
+        break;
+      case 'spec-wins':
+        resolvedValue = conflict.specValue;
+        break;
+      case 'prompt':
+        // Prompt keeps spec value pending user decision
+        resolvedValue = conflict.specValue;
+        break;
+    }
+
+    return {
+      field: conflict.field,
+      specValue: conflict.specValue,
+      githubValue: conflict.githubValue,
+      resolution: effectiveResolution,
+      resolvedValue,
+      resolvedAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Check if spec status and GitHub state represent a conflict.
+   */
+  private isStatusConflict(specStatus: string, githubState: string): boolean {
+    // "completed" spec + "open" GitHub = conflict
+    if (specStatus === 'completed' && githubState === 'open') return true;
+    // "planned" or "in-progress" spec + "closed" GitHub = conflict
+    if (specStatus !== 'completed' && githubState === 'closed') return true;
+    return false;
+  }
+}

package/plugins/specweave-github/lib/github-cross-repo-sync.js

@@ -0,0 +1,168 @@
+import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
+import { generateIssueBody } from "./github-issue-body-generator.js";
+async function crossRepoSync(stories, options) {
+  const result = {
+    created: [],
+    updated: [],
+    errors: [],
+    crossReferences: []
+  };
+  if (stories.length === 0) return result;
+  const env = getEnv(options.token);
+  const storyIssueMap = /* @__PURE__ */ new Map();
+  for (const story of stories) {
+    const repos = story.targetRepos.length > 0 ? story.targetRepos : [`${options.owner}/${options.defaultRepo}`];
+    const storyIssues = [];
+    for (const repo of repos) {
+      try {
+        const body = generateIssueBody({
+          id: story.id,
+          title: story.title,
+          description: story.description,
+          priority: story.priority,
+          acceptanceCriteria: story.acceptanceCriteria,
+          specId: story.specId
+        });
+        const title = `[${story.id}] ${story.title}`;
+        const existing = await searchIssue(story.id, repo, env);
+        if (existing) {
+          await updateIssue(existing.number, title, body, repo, env);
+          result.updated.push({
+            userStoryId: story.id,
+            repo,
+            issueNumber: existing.number,
+            issueUrl: `https://github.com/${repo}/issues/${existing.number}`
+          });
+          storyIssues.push({ repo, issueNumber: existing.number });
+        } else {
+          const created = await createIssue(title, body, story, repo, env);
+          result.created.push({
+            userStoryId: story.id,
+            repo,
+            issueNumber: created.number,
+            issueUrl: created.url,
+            issueNodeId: created.node_id
+          });
+          storyIssues.push({ repo, issueNumber: created.number });
+        }
+      } catch (err) {
+        result.errors.push({
+          userStoryId: story.id,
+          repo,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+    if (storyIssues.length > 1) {
+      storyIssueMap.set(story.id, storyIssues);
+    }
+  }
+  for (const [, issues] of storyIssueMap) {
+    for (const issue of issues) {
+      const linkedTo = issues.filter((i) => i.repo !== issue.repo);
+      result.crossReferences.push({
+        repo: issue.repo,
+        issueNumber: issue.issueNumber,
+        linkedTo
+      });
+      const crossRefSection = buildCrossRefSection(linkedTo);
+      try {
+        await appendToIssueBody(issue.issueNumber, issue.repo, crossRefSection, env);
+      } catch {
+      }
+    }
+  }
+  return result;
+}
+async function searchIssue(usId, repo, env) {
+  const res = await execFileNoThrow("gh", [
+    "issue",
+    "list",
+    "--repo",
+    repo,
+    "--search",
+    `[${usId}] in:title`,
+    "--json",
+    "number,title,node_id",
+    "--limit",
+    "1"
+  ], { env });
+  if (!res.success) {
+    throw new Error(`Search failed for ${repo}: ${res.stderr}`);
+  }
+  const issues = JSON.parse(res.stdout);
+  return issues.length > 0 ? issues[0] : null;
+}
+async function createIssue(title, body, story, repo, env) {
+  const res = await execFileNoThrow("gh", [
+    "issue",
+    "create",
+    "--repo",
+    repo,
+    "--title",
+    title,
+    "--body",
+    body,
+    "--label",
+    "user-story",
+    "--label",
+    `priority:${story.priority}`,
+    "--json",
+    "number,url,node_id"
+  ], { env });
+  if (!res.success) {
+    throw new Error(`Create failed for ${repo}: ${res.stderr}`);
+  }
+  return JSON.parse(res.stdout);
+}
+async function updateIssue(issueNumber, title, body, repo, env) {
+  const res = await execFileNoThrow("gh", [
+    "issue",
+    "edit",
+    String(issueNumber),
+    "--repo",
+    repo,
+    "--title",
+    title,
+    "--body",
+    body,
+    "--json",
+    "number,url"
+  ], { env });
+  if (!res.success) {
+    throw new Error(`Update failed for ${repo}: ${res.stderr}`);
+  }
+}
+async function appendToIssueBody(issueNumber, repo, section, env) {
+  const res = await execFileNoThrow("gh", [
+    "issue",
+    "edit",
+    String(issueNumber),
+    "--repo",
+    repo,
+    "--body",
+    section,
+    "--json",
+    "number,url"
+  ], { env });
+  if (!res.success) {
+    throw new Error(`Cross-ref update failed: ${res.stderr}`);
+  }
+}
+function buildCrossRefSection(linkedTo) {
+  const refs = linkedTo.map((l) => `- ${l.repo}#${l.issueNumber}`).join("\n");
+  return `
+
+---
+**Also tracked in:**
+${refs}`;
+}
+function getEnv(token) {
+  if (token) {
+    return { ...process.env, GH_TOKEN: token };
+  }
+  return process.env;
+}
+export {
+  crossRepoSync
+};

package/plugins/specweave-github/lib/github-cross-repo-sync.ts

@@ -0,0 +1,252 @@
+/**
+ * GitHub Cross-Repo Sync — Distributed multi-repo issue creation and linking
+ *
+ * Creates issues in different repos based on user story target repo tags,
+ * then adds cross-reference sections for stories spanning multiple repos.
+ *
+ * @module github-cross-repo-sync
+ */
+
+import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
+import { generateIssueBody } from './github-issue-body-generator.js';
+
+export interface CrossRepoUserStory {
+  id: string;
+  title: string;
+  description: string;
+  priority: string;
+  status: string;
+  acceptanceCriteria: Array<{ id: string; description: string; completed: boolean }>;
+  targetRepos: string[];
+  specId?: string;
+}
+
+export interface CrossRepoSyncOptions {
+  owner: string;
+  defaultRepo: string;
+  token?: string;
+}
+
+interface CreatedIssue {
+  userStoryId: string;
+  repo: string;
+  issueNumber: number;
+  issueUrl: string;
+  issueNodeId: string;
+}
+
+interface UpdatedIssue {
+  userStoryId: string;
+  repo: string;
+  issueNumber: number;
+  issueUrl: string;
+}
+
+interface CrossReference {
+  repo: string;
+  issueNumber: number;
+  linkedTo: Array<{ repo: string; issueNumber: number }>;
+}
+
+export interface CrossRepoSyncResult {
+  created: CreatedIssue[];
+  updated: UpdatedIssue[];
+  errors: Array<{ userStoryId: string; repo: string; error: string }>;
+  crossReferences: CrossReference[];
+}
+
+/**
+ * Create/update issues across multiple repos and add cross-references.
+ */
+export async function crossRepoSync(
+  stories: CrossRepoUserStory[],
+  options: CrossRepoSyncOptions,
+): Promise<CrossRepoSyncResult> {
+  const result: CrossRepoSyncResult = {
+    created: [],
+    updated: [],
+    errors: [],
+    crossReferences: [],
+  };
+
+  if (stories.length === 0) return result;
+
+  const env = getEnv(options.token);
+
+  // Track per-story issues for cross-referencing
+  const storyIssueMap = new Map<string, Array<{ repo: string; issueNumber: number }>>();
+
+  // Step 1: Create/update issues in target repos
+  for (const story of stories) {
+    const repos = story.targetRepos.length > 0
+      ? story.targetRepos
+      : [`${options.owner}/${options.defaultRepo}`];
+
+    const storyIssues: Array<{ repo: string; issueNumber: number }> = [];
+
+    for (const repo of repos) {
+      try {
+        const body = generateIssueBody({
+          id: story.id,
+          title: story.title,
+          description: story.description,
+          priority: story.priority,
+          acceptanceCriteria: story.acceptanceCriteria,
+          specId: story.specId,
+        });
+
+        const title = `[${story.id}] ${story.title}`;
+        const existing = await searchIssue(story.id, repo, env);
+
+        if (existing) {
+          await updateIssue(existing.number, title, body, repo, env);
+          result.updated.push({
+            userStoryId: story.id,
+            repo,
+            issueNumber: existing.number,
+            issueUrl: `https://github.com/${repo}/issues/${existing.number}`,
+          });
+          storyIssues.push({ repo, issueNumber: existing.number });
+        } else {
+          const created = await createIssue(title, body, story, repo, env);
+          result.created.push({
+            userStoryId: story.id,
+            repo,
+            issueNumber: created.number,
+            issueUrl: created.url,
+            issueNodeId: created.node_id,
+          });
+          storyIssues.push({ repo, issueNumber: created.number });
+        }
+      } catch (err) {
+        result.errors.push({
+          userStoryId: story.id,
+          repo,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    if (storyIssues.length > 1) {
+      storyIssueMap.set(story.id, storyIssues);
+    }
+  }
+
+  // Step 2: Add cross-references for multi-repo stories
+  for (const [, issues] of storyIssueMap) {
+    for (const issue of issues) {
+      const linkedTo = issues.filter(i => i.repo !== issue.repo);
+      result.crossReferences.push({
+        repo: issue.repo,
+        issueNumber: issue.issueNumber,
+        linkedTo,
+      });
+
+      // Add cross-reference comment via issue edit (append to body)
+      const crossRefSection = buildCrossRefSection(linkedTo);
+      try {
+        await appendToIssueBody(issue.issueNumber, issue.repo, crossRefSection, env);
+      } catch {
+        // Non-fatal: cross-ref is nice-to-have
+      }
+    }
+  }
+
+  return result;
+}
+
+async function searchIssue(
+  usId: string,
+  repo: string,
+  env: NodeJS.ProcessEnv,
+): Promise<{ number: number; title: string; node_id: string } | null> {
+  const res = await execFileNoThrow('gh', [
+    'issue', 'list',
+    '--repo', repo,
+    '--search', `[${usId}] in:title`,
+    '--json', 'number,title,node_id',
+    '--limit', '1',
+  ], { env });
+
+  if (!res.success) {
+    throw new Error(`Search failed for ${repo}: ${res.stderr}`);
+  }
+
+  const issues = JSON.parse(res.stdout);
+  return issues.length > 0 ? issues[0] : null;
+}
+
+async function createIssue(
+  title: string,
+  body: string,
+  story: CrossRepoUserStory,
+  repo: string,
+  env: NodeJS.ProcessEnv,
+): Promise<{ number: number; url: string; node_id: string }> {
+  const res = await execFileNoThrow('gh', [
+    'issue', 'create',
+    '--repo', repo,
+    '--title', title,
+    '--body', body,
+    '--label', 'user-story',
+    '--label', `priority:${story.priority}`,
+    '--json', 'number,url,node_id',
+  ], { env });
+
+  if (!res.success) {
+    throw new Error(`Create failed for ${repo}: ${res.stderr}`);
+  }
+
+  return JSON.parse(res.stdout);
+}
+
+async function updateIssue(
+  issueNumber: number,
+  title: string,
+  body: string,
+  repo: string,
+  env: NodeJS.ProcessEnv,
+): Promise<void> {
+  const res = await execFileNoThrow('gh', [
+    'issue', 'edit', String(issueNumber),
+    '--repo', repo,
+    '--title', title,
+    '--body', body,
+    '--json', 'number,url',
+  ], { env });
+
+  if (!res.success) {
+    throw new Error(`Update failed for ${repo}: ${res.stderr}`);
+  }
+}
+
+async function appendToIssueBody(
+  issueNumber: number,
+  repo: string,
+  section: string,
+  env: NodeJS.ProcessEnv,
+): Promise<void> {
+  // Use gh issue edit with --add-body
+  const res = await execFileNoThrow('gh', [
+    'issue', 'edit', String(issueNumber),
+    '--repo', repo,
+    '--body', section,
+    '--json', 'number,url',
+  ], { env });
+
+  if (!res.success) {
+    throw new Error(`Cross-ref update failed: ${res.stderr}`);
+  }
+}
+
+function buildCrossRefSection(linkedTo: Array<{ repo: string; issueNumber: number }>): string {
+  const refs = linkedTo.map(l => `- ${l.repo}#${l.issueNumber}`).join('\n');
+  return `\n\n---\n**Also tracked in:**\n${refs}`;
+}
+
+function getEnv(token?: string): NodeJS.ProcessEnv {
+  if (token) {
+    return { ...process.env, GH_TOKEN: token };
+  }
+  return process.env;
+}

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

@@ -0,0 +1,116 @@
+const DEFAULT_STATUS_MAPPING = {
+  "planned": "Todo",
+  "in-progress": "In Progress",
+  "completed": "Done"
+};
+const DEFAULT_PRIORITY_MAPPING = {
+  "P1": "Urgent",
+  "P2": "High",
+  "P3": "Medium",
+  "P4": "Low"
+};
+class GitHubFieldSync {
+  constructor(client, config) {
+    this.fieldsLoaded = false;
+    this.client = client;
+    this.config = config;
+  }
+  /**
+   * Load project fields and cache field IDs and option IDs.
+   */
+  async loadFields() {
+    if (this.fieldsLoaded) return;
+    const fields = await this.client.getProjectFields(this.config.projectId);
+    for (const field of fields) {
+      if (field.name === "Status" && field.options) {
+        this.statusField = {
+          id: field.id,
+          name: field.name,
+          options: new Map(field.options.map((o) => [o.name, o.id]))
+        };
+      } else if (field.name === "Priority" && field.options) {
+        this.priorityField = {
+          id: field.id,
+          name: field.name,
+          options: new Map(field.options.map((o) => [o.name, o.id]))
+        };
+      }
+    }
+    this.fieldsLoaded = true;
+  }
+  /**
+   * Sync fields for one or more items.
+   * Auto-calls loadFields if not called yet.
+   */
+  async syncItemFields(items) {
+    if (!this.fieldsLoaded) {
+      await this.loadFields();
+    }
+    const result = { updated: [], warnings: [] };
+    for (const item of items) {
+      if (item.status !== void 0) {
+        await this.syncField(
+          item,
+          "Status",
+          item.status,
+          this.statusField,
+          this.config.statusFieldMapping ?? DEFAULT_STATUS_MAPPING,
+          result
+        );
+      }
+      if (item.priority !== void 0) {
+        await this.syncField(
+          item,
+          "Priority",
+          item.priority,
+          this.priorityField,
+          this.config.priorityFieldMapping ?? DEFAULT_PRIORITY_MAPPING,
+          result
+        );
+      }
+    }
+    return result;
+  }
+  async syncField(item, fieldName, value, cachedField, mapping, result) {
+    if (!cachedField) {
+      result.warnings.push({
+        itemId: item.itemId,
+        field: fieldName,
+        message: `${fieldName} field not found on project`
+      });
+      return;
+    }
+    const mappedValue = mapping[value];
+    if (!mappedValue) {
+      result.warnings.push({
+        itemId: item.itemId,
+        field: fieldName,
+        message: `No mapping found for ${fieldName} value "${value}"`
+      });
+      return;
+    }
+    const optionId = cachedField.options.get(mappedValue);
+    if (!optionId) {
+      result.warnings.push({
+        itemId: item.itemId,
+        field: fieldName,
+        message: `Option "${mappedValue}" not found on ${fieldName} field`
+      });
+      return;
+    }
+    await this.client.updateItemFieldValue(
+      this.config.projectId,
+      item.itemId,
+      cachedField.id,
+      { singleSelectOptionId: optionId }
+    );
+    result.updated.push({
+      itemId: item.itemId,
+      field: fieldName,
+      value: mappedValue
+    });
+  }
+}
+export {
+  GitHubFieldSync
+};