specweave 0.18.0 → 0.18.1

package/plugins/specweave-ado/lib/enhanced-ado-sync.js

@@ -0,0 +1,170 @@
+import { AdoClientV2 } from "./ado-client-v2.js";
+import { EnhancedContentBuilder } from "../../../src/core/sync/enhanced-content-builder.js";
+import { SpecIncrementMapper } from "../../../src/core/sync/spec-increment-mapper.js";
+import { parseSpecContent } from "../../../src/core/spec-content-sync.js";
+import path from "path";
+import fs from "fs/promises";
+async function syncSpecToAdoWithEnhancedContent(options) {
+  const { specPath, organization, project, dryRun = false, verbose = false } = options;
+  try {
+    const baseSpec = await parseSpecContent(specPath);
+    if (!baseSpec) {
+      return {
+        success: false,
+        action: "error",
+        error: "Failed to parse spec content"
+      };
+    }
+    if (verbose) {
+      console.log(`\u{1F4C4} Parsed spec: ${baseSpec.identifier.compact}`);
+    }
+    const specId = baseSpec.identifier.full || baseSpec.identifier.compact;
+    const rootDir = await findSpecWeaveRoot(specPath);
+    const mapper = new SpecIncrementMapper(rootDir);
+    const mapping = await mapper.mapSpecToIncrements(specId);
+    if (verbose) {
+      console.log(`\u{1F517} Found ${mapping.increments.length} related increments`);
+    }
+    const taskMapping = buildTaskMapping(mapping.increments, organization, project);
+    const architectureDocs = await findArchitectureDocs(rootDir, specId);
+    const enhancedSpec = {
+      ...baseSpec,
+      summary: baseSpec.description,
+      taskMapping,
+      architectureDocs
+    };
+    const builder = new EnhancedContentBuilder();
+    const description = builder.buildExternalDescription(enhancedSpec);
+    if (verbose) {
+      console.log(`\u{1F4DD} Generated description: ${description.length} characters`);
+    }
+    if (dryRun) {
+      console.log("\u{1F50D} DRY RUN - Would create/update feature with:");
+      console.log(`   Title: ${baseSpec.title}`);
+      console.log(`   Description length: ${description.length}`);
+      return {
+        success: true,
+        action: "no-change",
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    }
+    if (!organization || !project) {
+      return {
+        success: false,
+        action: "error",
+        error: "Azure DevOps organization/project not specified"
+      };
+    }
+    const profile = {
+      provider: "ado",
+      displayName: `${organization}/${project}`,
+      config: {
+        organization,
+        project
+      },
+      timeRange: { default: "1M", max: "6M" }
+    };
+    const pat = process.env.AZURE_DEVOPS_PAT || "";
+    const client = new AdoClientV2(profile, pat);
+    const existingFeature = await findExistingFeature(client, baseSpec.identifier.compact);
+    let result;
+    if (existingFeature) {
+      await client.updateWorkItem(existingFeature.id, {
+        title: `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
+        description
+      });
+      result = {
+        success: true,
+        action: "updated",
+        featureId: existingFeature.id,
+        featureUrl: `https://dev.azure.com/${organization}/${project}/_workitems/edit/${existingFeature.id}`,
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    } else {
+      const feature = await client.createEpic({
+        title: `[${baseSpec.identifier.compact}] ${baseSpec.title}`,
+        description,
+        tags: ["spec", "external-tool-sync"]
+      });
+      result = {
+        success: true,
+        action: "created",
+        featureId: feature.id,
+        featureUrl: `https://dev.azure.com/${organization}/${project}/_workitems/edit/${feature.id}`,
+        tasksLinked: taskMapping?.tasks.length || 0
+      };
+    }
+    if (verbose) {
+      console.log(`\u2705 ${result.action === "created" ? "Created" : "Updated"} feature #${result.featureId}`);
+    }
+    return result;
+  } catch (error) {
+    return {
+      success: false,
+      action: "error",
+      error: error.message
+    };
+  }
+}
+async function findSpecWeaveRoot(specPath) {
+  let currentDir = path.dirname(specPath);
+  while (true) {
+    const specweaveDir = path.join(currentDir, ".specweave");
+    try {
+      await fs.access(specweaveDir);
+      return currentDir;
+    } catch {
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        throw new Error(".specweave directory not found");
+      }
+      currentDir = parentDir;
+    }
+  }
+}
+function buildTaskMapping(increments, organization, project) {
+  if (increments.length === 0) return void 0;
+  const firstIncrement = increments[0];
+  const tasks = firstIncrement.tasks.map((task) => ({
+    id: task.id,
+    title: task.title,
+    userStories: task.userStories
+  }));
+  return {
+    incrementId: firstIncrement.id,
+    tasks,
+    tasksUrl: `https://dev.azure.com/${organization}/${project}/_git/repo?path=/.specweave/increments/${firstIncrement.id}/tasks.md`
+  };
+}
+async function findArchitectureDocs(rootDir, specId) {
+  const docs = [];
+  const archDir = path.join(rootDir, ".specweave/docs/internal/architecture");
+  try {
+    const adrDir = path.join(archDir, "adr");
+    try {
+      const adrs = await fs.readdir(adrDir);
+      const relatedAdrs = adrs.filter((file) => file.includes(specId.replace("spec-", "")));
+      for (const adr of relatedAdrs) {
+        docs.push({
+          type: "adr",
+          path: path.join(adrDir, adr),
+          title: adr.replace(".md", "").replace(/-/g, " ")
+        });
+      }
+    } catch {
+    }
+  } catch {
+  }
+  return docs;
+}
+async function findExistingFeature(client, specId) {
+  try {
+    const features = await client.queryWorkItems(`[System.Title] Contains '[${specId}]' AND [System.WorkItemType] = 'Feature'`);
+    return features[0] || null;
+  } catch {
+    return null;
+  }
+}
+export {
+  syncSpecToAdoWithEnhancedContent
+};

package/plugins/specweave-github/hooks/post-task-completion.sh

@@ -199,6 +199,38 @@ else
   fi
 fi
 
+# ============================================================================
+# EPIC GITHUB ISSUE SYNC (Update Epic issue with fresh task progress)
+# ============================================================================
+
+echo "[$(date)] [GitHub] 🔄 Checking for Epic GitHub issue update..." >> "$DEBUG_LOG" 2>/dev/null || true
+
+# Find active increment ID
+ACTIVE_INCREMENT=$(ls -t .specweave/increments/ | grep -v '^\.' | while read inc; do
+  if [ -f ".specweave/increments/$inc/metadata.json" ]; then
+    STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' ".specweave/increments/$inc/metadata.json" 2>/dev/null | sed 's/.*"\([^"]*\)".*/\1/' || true)
+    if [ "$STATUS" = "active" ]; then
+      echo "$inc"
+      break
+    fi
+  fi
+done | head -1)
+
+if [ -n "$ACTIVE_INCREMENT" ]; then
+  echo "[$(date)] [GitHub] 🎯 Active increment: $ACTIVE_INCREMENT" >> "$DEBUG_LOG" 2>/dev/null || true
+
+  # Run Epic sync script (silently, errors logged to debug log)
+  if [ -f "$PROJECT_ROOT/scripts/update-epic-github-issue.sh" ]; then
+    echo "[$(date)] [GitHub] 🚀 Updating Epic GitHub issue..." >> "$DEBUG_LOG" 2>/dev/null || true
+    "$PROJECT_ROOT/scripts/update-epic-github-issue.sh" "$ACTIVE_INCREMENT" >> "$DEBUG_LOG" 2>&1 || true
+    echo "[$(date)] [GitHub] ✅ Epic sync complete (see logs for details)" >> "$DEBUG_LOG" 2>/dev/null || true
+  else
+    echo "[$(date)] [GitHub] ⚠️  Epic sync script not found, skipping" >> "$DEBUG_LOG" 2>/dev/null || true
+  fi
+else
+  echo "[$(date)] [GitHub] ℹ️  No active increment found, skipping Epic sync" >> "$DEBUG_LOG" 2>/dev/null || true
+fi
+
 # ============================================================================
 # OUTPUT TO CLAUDE
 # ============================================================================

package/plugins/specweave-github/lib/epic-content-builder.js

@@ -0,0 +1,227 @@
+import { readdir, readFile } from "fs/promises";
+import { existsSync } from "fs";
+import * as path from "path";
+import * as yaml from "yaml";
+class EpicContentBuilder {
+  constructor(epicFolder, projectRoot) {
+    this.epicFolder = epicFolder;
+    this.projectRoot = projectRoot;
+  }
+  /**
+   * Build hierarchical GitHub issue body
+   *
+   * Format:
+   * - Epic overview
+   * - User Stories section (checkable, with status + increment)
+   * - Tasks section (grouped by User Story)
+   */
+  async buildIssueBody() {
+    const epicData = await this.readEpicMetadata();
+    const userStories = await this.readUserStories();
+    const overview = this.buildOverviewSection(epicData);
+    const userStoriesSection = this.buildUserStoriesSection(userStories);
+    const tasksSection = this.buildTasksSection(userStories);
+    return `${overview}
+
+---
+
+${userStoriesSection}
+
+---
+
+${tasksSection}
+
+---
+
+\u{1F916} Auto-created by SpecWeave Epic Sync`;
+  }
+  /**
+   * Read Epic FEATURE.md frontmatter
+   */
+  async readEpicMetadata() {
+    const featurePath = path.join(this.epicFolder, "FEATURE.md");
+    const content = await readFile(featurePath, "utf-8");
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match) {
+      throw new Error("FEATURE.md missing YAML frontmatter");
+    }
+    return yaml.parse(match[1]);
+  }
+  /**
+   * Read all user stories from us-*.md files
+   */
+  async readUserStories() {
+    const files = await readdir(this.epicFolder);
+    const usFiles = files.filter((f) => f.startsWith("us-") && f.endsWith(".md"));
+    const userStories = [];
+    for (const file of usFiles.sort()) {
+      const filePath = path.join(this.epicFolder, file);
+      const content = await readFile(filePath, "utf-8");
+      const match = content.match(/^---\n([\s\S]*?)\n---/);
+      if (!match) {
+        console.warn(`   \u26A0\uFE0F  ${file} missing frontmatter, skipping`);
+        continue;
+      }
+      const frontmatter = yaml.parse(match[1]);
+      const bodyContent = content.slice(match[0].length).trim();
+      const incrementMatch = bodyContent.match(/\*\*Increment\*\*:\s*\[([^\]]+)\]/);
+      const increment = incrementMatch ? incrementMatch[1] : null;
+      const tasks = await this.extractTasksForUserStory(
+        frontmatter.id,
+        increment,
+        bodyContent
+      );
+      userStories.push({
+        id: frontmatter.id,
+        title: frontmatter.title,
+        status: this.normalizeStatus(frontmatter.status),
+        increment,
+        tasks
+      });
+    }
+    return userStories;
+  }
+  /**
+   * Extract tasks for a user story from its Implementation section
+   */
+  async extractTasksForUserStory(userStoryId, incrementId, content) {
+    if (!incrementId) {
+      return [];
+    }
+    const incrementFolder = path.join(
+      this.projectRoot,
+      ".specweave",
+      "increments",
+      incrementId
+    );
+    if (!existsSync(incrementFolder)) {
+      console.warn(`   \u26A0\uFE0F  Increment folder not found: ${incrementId}`);
+      return [];
+    }
+    const tasksPath = path.join(incrementFolder, "tasks.md");
+    if (!existsSync(tasksPath)) {
+      console.warn(`   \u26A0\uFE0F  tasks.md not found in ${incrementId}`);
+      return [];
+    }
+    const tasksContent = await readFile(tasksPath, "utf-8");
+    const taskLinkPattern = /- \[([T-\d]+):\s*([^\]]+)\]/g;
+    const taskLinks = [];
+    let match;
+    while ((match = taskLinkPattern.exec(content)) !== null) {
+      taskLinks.push({
+        id: match[1],
+        // e.g., "T-001"
+        title: match[2].trim()
+      });
+    }
+    const tasks = [];
+    for (const taskLink of taskLinks) {
+      const taskPattern = new RegExp(
+        `###\\s+${taskLink.id}:\\s*([^\\n]+)[\\s\\S]*?\\*\\*Status\\*\\*:\\s*\\[([x\\s])\\]`,
+        "i"
+      );
+      const taskMatch = tasksContent.match(taskPattern);
+      const isCompleted = taskMatch ? taskMatch[2] === "x" : false;
+      tasks.push({
+        id: taskLink.id,
+        title: taskLink.title,
+        status: isCompleted,
+        userStoryId
+      });
+    }
+    return tasks;
+  }
+  /**
+   * Build overview section
+   */
+  buildOverviewSection(epic) {
+    return `# [${epic.id}] ${epic.title}
+
+**Status**: ${epic.status}
+**Created**: ${epic.created}
+**Last Updated**: ${epic.last_updated}`;
+  }
+  /**
+   * Build User Stories section
+   */
+  buildUserStoriesSection(userStories) {
+    const total = userStories.length;
+    const completed = userStories.filter((us) => us.status === "complete").length;
+    const percentage = total > 0 ? Math.round(completed / total * 100) : 0;
+    let section = `## User Stories
+
+Progress: ${completed}/${total} user stories complete (${percentage}%)
+
+`;
+    for (const us of userStories) {
+      const checkbox = us.status === "complete" ? "[x]" : "[ ]";
+      const statusEmoji = this.getStatusEmoji(us.status);
+      const incrementLink = us.increment ? `[${us.increment}](../../increments/${us.increment}/)` : "TBD";
+      section += `- ${checkbox} **${us.id}: ${us.title}** (${statusEmoji} ${us.status} | Increment: ${incrementLink})
+`;
+    }
+    return section;
+  }
+  /**
+   * Build Tasks section (grouped by User Story)
+   */
+  buildTasksSection(userStories) {
+    const totalTasks = userStories.reduce((sum, us) => sum + us.tasks.length, 0);
+    const completedTasks = userStories.reduce(
+      (sum, us) => sum + us.tasks.filter((t) => t.status).length,
+      0
+    );
+    const percentage = totalTasks > 0 ? Math.round(completedTasks / totalTasks * 100) : 0;
+    let section = `## Tasks by User Story
+
+Progress: ${completedTasks}/${totalTasks} tasks complete (${percentage}%)
+
+`;
+    for (const us of userStories) {
+      if (us.tasks.length === 0) {
+        continue;
+      }
+      const incrementLink = us.increment ? `[${us.increment}](../../increments/${us.increment}/tasks.md)` : "TBD";
+      section += `### ${us.id}: ${us.title} (Increment: ${incrementLink})
+
+`;
+      for (const task of us.tasks) {
+        const checkbox = task.status ? "[x]" : "[ ]";
+        section += `- ${checkbox} ${task.id}: ${task.title}
+`;
+      }
+      section += "\n";
+    }
+    return section;
+  }
+  /**
+   * Normalize status values
+   */
+  normalizeStatus(status) {
+    const normalized = status.toLowerCase();
+    if (normalized === "complete" || normalized === "completed") return "complete";
+    if (normalized === "active" || normalized === "in-progress") return "active";
+    if (normalized === "planning") return "planning";
+    return "not-started";
+  }
+  /**
+   * Get status emoji
+   */
+  getStatusEmoji(status) {
+    switch (status) {
+      case "complete":
+        return "\u2705";
+      case "active":
+        return "\u{1F6A7}";
+      case "planning":
+        return "\u{1F4CB}";
+      case "not-started":
+        return "\u23F3";
+      default:
+        return "\u2753";
+    }
+  }
+}
+export {
+  EpicContentBuilder
+};