specweave 0.28.15 → 0.28.19

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

@@ -1,18 +1,13 @@
 /**
  * GitHub Feature Sync - Universal Hierarchy Implementation
  *
- * Architecture (CORRECT):
- * - Feature (FS-033) → GitHub Milestone (Container)
- * - User Story (US-001, US-002, etc.) → GitHub Issue (Trackable item)
- * - Tasks (T-001, T-002, etc.) → Checkboxes in User Story issue body
+ * Architecture:
+ * - Feature (FS-XXX) → GitHub Milestone (Container)
+ * - User Story (US-XXX) → GitHub Issue with format [FS-XXX][US-YYY] Title
+ * - Tasks (T-XXX) → Checkboxes in User Story issue body
  *
- * This implements the TRUE Universal Hierarchy architecture for GitHub.
- *
- * Key Differences from old github-epic-sync.ts:
- * - ❌ OLD: Feature/Increment → GitHub Issue (WRONG!)
- * - ✅ NEW: User Story → GitHub Issue (CORRECT!)
- * - ✅ Creates ONE issue PER user story file (not one per increment)
- * - ✅ Reads us-*.md files from specs/{project}/FS-XXX/
+ * This implements the Universal Hierarchy architecture for GitHub sync.
+ * Creates ONE issue PER user story file from specs/{project}/FS-XXX/us-*.md
  */
 
 import { readdir, readFile, writeFile } from 'fs/promises';

package/plugins/specweave-github/lib/github-increment-sync-cli.js

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "fs";
+import * as fs from "fs/promises";
+import * as path from "path";
+import { IncrementIssueBuilder } from "./increment-issue-builder.js";
+import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
+async function loadGitHubConfig() {
+  const projectRoot = process.cwd();
+  const configPath = path.join(projectRoot, ".specweave/config.json");
+  let owner = process.env.GITHUB_OWNER || "";
+  let repo = process.env.GITHUB_REPO || "";
+  const token = process.env.GITHUB_TOKEN || "";
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, "utf-8"));
+      if (config.sync?.github?.owner && config.sync?.github?.repo) {
+        owner = config.sync.github.owner;
+        repo = config.sync.github.repo;
+      } else if (config.multiProject?.enabled && config.multiProject?.activeProject) {
+        const activeProject = config.multiProject.activeProject;
+        const projectConfig = config.multiProject.projects?.[activeProject];
+        if (projectConfig?.externalTools?.github?.repository) {
+          const parts = projectConfig.externalTools.github.repository.split("/");
+          if (parts.length === 2) {
+            owner = parts[0];
+            repo = parts[1];
+          }
+        }
+      } else if (config.sync?.activeProfile && config.sync?.profiles) {
+        const profile = config.sync.profiles[config.sync.activeProfile];
+        if (profile?.config?.owner && profile?.config?.repo) {
+          owner = profile.config.owner;
+          repo = profile.config.repo;
+        }
+      }
+    } catch (error) {
+      console.error("\u26A0\uFE0F  Failed to parse config.json:", error);
+    }
+  }
+  if (!owner || !repo) {
+    const result = await execFileNoThrow("git", ["remote", "get-url", "origin"]);
+    if (result.exitCode === 0 && result.stdout) {
+      const remoteUrl = result.stdout.trim();
+      const match = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/.]+)/);
+      if (match) {
+        owner = owner || match[1];
+        repo = repo || match[2];
+      }
+    }
+  }
+  if (!token) {
+    console.error("\u274C GITHUB_TOKEN not set");
+    console.error("   Set it in .env file or export GITHUB_TOKEN=ghp_xxx");
+    return null;
+  }
+  if (!owner || !repo) {
+    console.error("\u274C Could not detect GitHub owner/repo");
+    console.error("   Set sync.github.owner and sync.github.repo in .specweave/config.json");
+    return null;
+  }
+  return { owner, repo, token };
+}
+async function findIncrementFolder(incrementId) {
+  const projectRoot = process.cwd();
+  const incrementsDir = path.join(projectRoot, ".specweave/increments");
+  if (!existsSync(incrementsDir)) {
+    return null;
+  }
+  const entries = await fs.readdir(incrementsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith("_")) continue;
+    if (entry.name === incrementId) {
+      return path.join(incrementsDir, entry.name);
+    }
+    if (entry.name.startsWith(incrementId + "-")) {
+      return path.join(incrementsDir, entry.name);
+    }
+  }
+  return null;
+}
+async function findExistingIssue(owner, repo, featureId) {
+  const result = await execFileNoThrow("gh", [
+    "search",
+    "issues",
+    `repo:${owner}/${repo}`,
+    `"[${featureId}]" in:title`,
+    "is:open",
+    "--json",
+    "number,title",
+    "--limit",
+    "5"
+  ]);
+  if (result.exitCode !== 0 || !result.stdout.trim()) {
+    return null;
+  }
+  try {
+    const issues = JSON.parse(result.stdout);
+    if (issues.length > 0) {
+      return issues[0].number;
+    }
+  } catch {
+  }
+  return null;
+}
+async function createGitHubIssue(owner, repo, title, body, labels) {
+  const args = [
+    "issue",
+    "create",
+    "--repo",
+    `${owner}/${repo}`,
+    "--title",
+    title,
+    "--body",
+    body
+  ];
+  if (labels.length > 0) {
+    args.push("--label", labels.join(","));
+  }
+  const result = await execFileNoThrow("gh", args);
+  if (result.exitCode !== 0) {
+    throw new Error(`Failed to create issue: ${result.stderr || result.stdout}`);
+  }
+  const urlMatch = result.stdout.match(/https:\/\/github\.com\/[^\s]+\/issues\/(\d+)/);
+  if (!urlMatch) {
+    throw new Error("Could not parse issue URL from gh output");
+  }
+  return {
+    number: parseInt(urlMatch[1], 10),
+    url: urlMatch[0]
+  };
+}
+async function updateGitHubIssue(owner, repo, issueNumber, body) {
+  const result = await execFileNoThrow("gh", [
+    "issue",
+    "edit",
+    String(issueNumber),
+    "--repo",
+    `${owner}/${repo}`,
+    "--body",
+    body
+  ]);
+  if (result.exitCode !== 0) {
+    throw new Error(`Failed to update issue: ${result.stderr || result.stdout}`);
+  }
+}
+function loadExistingGitHubLink(incrementPath) {
+  const metadataPath = path.join(incrementPath, "metadata.json");
+  if (!existsSync(metadataPath)) {
+    return null;
+  }
+  try {
+    const metadata = JSON.parse(readFileSync(metadataPath, "utf-8"));
+    if (metadata.github?.issue) {
+      return {
+        issue: metadata.github.issue,
+        url: metadata.github.url
+      };
+    }
+    if (metadata.sync?.issueNumber) {
+      return {
+        issue: metadata.sync.issueNumber,
+        url: metadata.sync.issueUrl
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function updateIncrementMetadata(incrementPath, issueNumber, issueUrl) {
+  const metadataPath = path.join(incrementPath, "metadata.json");
+  let metadata = {};
+  if (existsSync(metadataPath)) {
+    try {
+      metadata = JSON.parse(readFileSync(metadataPath, "utf-8"));
+    } catch {
+    }
+  }
+  metadata.github = {
+    issue: issueNumber,
+    url: issueUrl,
+    lastSync: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2) + "\n");
+}
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    console.log("Usage: node github-increment-sync-cli.js <increment-id> [options]");
+    console.log("");
+    console.log("Arguments:");
+    console.log("  increment-id   Increment ID (e.g., 0063 or 0063-fix-external-import)");
+    console.log("");
+    console.log("Options:");
+    console.log("  --force        Force create even if issue exists");
+    console.log("  --dry-run      Preview issue without creating");
+    console.log("");
+    console.log("Environment:");
+    console.log("  GITHUB_TOKEN   Required - GitHub personal access token");
+    console.log("");
+    console.log("Example:");
+    console.log("  GITHUB_TOKEN=ghp_xxx node github-increment-sync-cli.js 0063");
+    process.exit(args.length === 0 ? 1 : 0);
+  }
+  const incrementId = args[0];
+  const force = args.includes("--force");
+  const dryRun = args.includes("--dry-run");
+  console.log(`
+\u{1F419} GitHub Increment Sync CLI`);
+  console.log(`   Increment: ${incrementId}`);
+  const incrementPath = await findIncrementFolder(incrementId);
+  if (!incrementPath) {
+    console.error(`\u274C Increment not found: ${incrementId}`);
+    console.error("   Check: ls .specweave/increments/");
+    process.exit(1);
+  }
+  const fullIncrementId = path.basename(incrementPath);
+  console.log(`   Found: ${fullIncrementId}`);
+  let config = null;
+  if (!dryRun) {
+    config = await loadGitHubConfig();
+    if (!config) {
+      process.exit(1);
+    }
+    console.log(`   Repository: ${config.owner}/${config.repo}`);
+  } else {
+    config = await loadGitHubConfig().catch(() => null);
+    if (config) {
+      console.log(`   Repository: ${config.owner}/${config.repo}`);
+    } else {
+      console.log(`   Repository: (not detected - dry run mode)`);
+    }
+  }
+  const projectRoot = process.cwd();
+  const builder = new IncrementIssueBuilder(incrementPath, projectRoot);
+  try {
+    console.log(`
+\u{1F504} Parsing increment spec.md...`);
+    const incrementData = await builder.parse();
+    console.log(`   \u{1F4E6} Title: ${incrementData.title}`);
+    console.log(`   \u{1F4DD} User Stories: ${incrementData.userStories.length}`);
+    const totalACs = incrementData.userStories.reduce(
+      (sum, us) => sum + us.acceptanceCriteria.length,
+      0
+    );
+    console.log(`   \u2713 Acceptance Criteria: ${totalACs}`);
+    const githubRepo = config ? `${config.owner}/${config.repo}` : void 0;
+    const issue = builder.buildIncrementIssue(incrementData, githubRepo);
+    console.log(`
+\u{1F4CB} Issue Preview:`);
+    console.log(`   Title: ${issue.title}`);
+    console.log(`   Labels: ${issue.labels.join(", ")}`);
+    if (dryRun) {
+      console.log(`
+\u{1F4C4} Issue Body Preview:
+`);
+      console.log(issue.body);
+      console.log(`
+\u2705 Dry run complete (no issue created)`);
+      process.exit(0);
+    }
+    if (!config) {
+      console.error("\u274C GitHub config not available");
+      process.exit(1);
+    }
+    const metadataLink = loadExistingGitHubLink(incrementPath);
+    if (metadataLink) {
+      console.log(`
+\u{1F4CE} Found existing issue link in metadata: #${metadataLink.issue}`);
+      console.log(`\u{1F504} Updating issue #${metadataLink.issue} with new format...`);
+      await updateGitHubIssue(config.owner, config.repo, metadataLink.issue, issue.body);
+      console.log(`   \u2705 Body updated with User Stories and ACs`);
+      const updateTitleResult = await execFileNoThrow("gh", [
+        "issue",
+        "edit",
+        String(metadataLink.issue),
+        "--repo",
+        `${config.owner}/${config.repo}`,
+        "--title",
+        issue.title
+      ]);
+      if (updateTitleResult.exitCode === 0) {
+        console.log(`   \u2705 Title updated to: ${issue.title}`);
+      } else {
+        console.log(`   \u26A0\uFE0F  Could not update title (may need permissions)`);
+      }
+      await updateIncrementMetadata(
+        incrementPath,
+        metadataLink.issue,
+        `https://github.com/${config.owner}/${config.repo}/issues/${metadataLink.issue}`
+      );
+      console.log(`
+\u2705 Sync complete!`);
+      console.log(`   \u{1F517} https://github.com/${config.owner}/${config.repo}/issues/${metadataLink.issue}`);
+      process.exit(0);
+    }
+    const featureId = incrementData.frontmatter.feature_id || `FS-${fullIncrementId.match(/^(\d+)/)?.[1]?.padStart(3, "0") || "UNKNOWN"}`;
+    console.log(`
+\u{1F50D} Searching GitHub for existing issue [${featureId}]...`);
+    const existingIssue = await findExistingIssue(config.owner, config.repo, featureId);
+    if (existingIssue) {
+      console.log(`   Found existing issue: #${existingIssue}`);
+      console.log(`\u{1F504} Updating issue #${existingIssue}...`);
+      await updateGitHubIssue(config.owner, config.repo, existingIssue, issue.body);
+      console.log(`   \u2705 Issue #${existingIssue} updated`);
+      await updateIncrementMetadata(
+        incrementPath,
+        existingIssue,
+        `https://github.com/${config.owner}/${config.repo}/issues/${existingIssue}`
+      );
+      console.log(`
+\u2705 Sync complete!`);
+      console.log(`   \u{1F517} https://github.com/${config.owner}/${config.repo}/issues/${existingIssue}`);
+      process.exit(0);
+    }
+    console.log(`   No existing issue found`);
+    console.log(`
+\u{1F680} Creating GitHub issue...`);
+    const created = await createGitHubIssue(
+      config.owner,
+      config.repo,
+      issue.title,
+      issue.body,
+      issue.labels
+    );
+    console.log(`   \u2705 Issue #${created.number} created`);
+    await updateIncrementMetadata(incrementPath, created.number, created.url);
+    console.log(`   \u{1F4DD} Metadata updated`);
+    console.log(`
+\u2705 Sync complete!`);
+    console.log(`   \u{1F517} ${created.url}`);
+    process.exit(0);
+  } catch (error) {
+    console.error(`
+\u274C Sync failed:`, error);
+    process.exit(1);
+  }
+}
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});