specweave 1.0.506 → 1.0.508

package/plugins/specweave/lib/integrations/github/github-push-sync.ts

@@ -0,0 +1,188 @@
+/**
+ * GitHub Push Sync — User Stories → GitHub Issues
+ *
+ * Creates or updates GitHub issues from SpecWeave user stories.
+ * Uses `gh` CLI for all operations (no direct HTTP).
+ *
+ * @module github-push-sync
+ */
+
+import { execFileNoThrow } from '../../../../../src/utils/execFileNoThrow.js';
+import { generateIssueBody } from './github-issue-body-generator.js';
+import { SyncError } from '../../../../../src/core/errors/sync-error.js';
+
+/**
+ * Extract HTTP status code from gh CLI stderr output.
+ * gh CLI typically outputs "HTTP 401: Bad credentials" or similar.
+ */
+function parseHttpStatus(stderr: string): number {
+  const match = stderr.match(/HTTP\s+(\d{3})/);
+  return match ? parseInt(match[1], 10) : 0;
+}
+
+export interface UserStoryForSync {
+  id: string;
+  title: string;
+  description: string;
+  priority: string;
+  status: string;
+  acceptanceCriteria: Array<{ id: string; description: string; completed: boolean }>;
+  specId?: string;
+}
+
+export interface PushSyncOptions {
+  owner: string;
+  repo: string;
+  token?: string;
+  dryRun?: boolean;
+}
+
+export interface PushSyncResult {
+  created: Array<{ userStoryId: string; issueNumber: number; issueUrl: string; issueNodeId: string }>;
+  updated: Array<{ userStoryId: string; issueNumber: number; issueUrl: string }>;
+  errors: Array<{ userStoryId: string; error: string }>;
+}
+
+/**
+ * Push sync user stories to GitHub issues.
+ * For each US: search by [US-XXX] prefix, create if new, update if existing.
+ */
+export async function pushSyncUserStories(
+  userStories: UserStoryForSync[],
+  options: PushSyncOptions,
+): Promise<PushSyncResult> {
+  const result: PushSyncResult = { created: [], updated: [], errors: [] };
+
+  if (options.dryRun) {
+    return result;
+  }
+
+  const env = getEnv(options.token);
+  const repoSlug = `${options.owner}/${options.repo}`;
+
+  for (const us of userStories) {
+    try {
+      const existing = await searchIssueByPrefix(us.id, repoSlug, env);
+
+      const body = generateIssueBody({
+        id: us.id,
+        title: us.title,
+        description: us.description,
+        priority: us.priority,
+        acceptanceCriteria: us.acceptanceCriteria,
+        specId: us.specId,
+      });
+
+      const title = `[${us.id}] ${us.title}`;
+
+      if (existing) {
+        // Update existing issue
+        const updated = await updateIssue(existing.number, title, body, repoSlug, env);
+        result.updated.push({
+          userStoryId: us.id,
+          issueNumber: updated.number,
+          issueUrl: updated.url,
+        });
+      } else {
+        // Create new issue
+        const created = await createIssue(title, body, us, repoSlug, env);
+        result.created.push({
+          userStoryId: us.id,
+          issueNumber: created.number,
+          issueUrl: created.url,
+          issueNodeId: created.node_id,
+        });
+      }
+    } catch (err) {
+      result.errors.push({
+        userStoryId: us.id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return result;
+}
+
+async function searchIssueByPrefix(
+  usId: string,
+  repoSlug: string,
+  env: NodeJS.ProcessEnv,
+): Promise<{ number: number; title: string; node_id: string } | null> {
+  const res = await execFileNoThrow('gh', [
+    'issue', 'list',
+    '--repo', repoSlug,
+    '--state', 'all',
+    '--search', `[${usId}] in:title`,
+    '--json', 'number,title,node_id',
+    '--limit', '1',
+  ], { env });
+
+  if (!res.success) {
+    const status = parseHttpStatus(res.stderr);
+    throw new SyncError('github', status, res.stderr, `Search failed: ${res.stderr}`);
+  }
+
+  const issues = JSON.parse(res.stdout);
+  return issues.length > 0 ? issues[0] : null;
+}
+
+async function createIssue(
+  title: string,
+  body: string,
+  us: UserStoryForSync,
+  repoSlug: string,
+  env: NodeJS.ProcessEnv,
+): Promise<{ number: number; url: string; node_id: string }> {
+  const args = [
+    'issue', 'create',
+    '--repo', repoSlug,
+    '--title', title,
+    '--body', body,
+    '--label', 'user-story',
+    '--label', `spec:${us.specId || 'unknown'}`,
+    '--label', `priority:${us.priority}`,
+    '--json', 'number,url,node_id',
+  ];
+
+  const res = await execFileNoThrow('gh', args, { env });
+
+  if (!res.success) {
+    const status = parseHttpStatus(res.stderr);
+    throw new SyncError('github', status, res.stderr, `Create failed: ${res.stderr}`);
+  }
+
+  return JSON.parse(res.stdout);
+}
+
+async function updateIssue(
+  issueNumber: number,
+  title: string,
+  body: string,
+  repoSlug: string,
+  env: NodeJS.ProcessEnv,
+): Promise<{ number: number; url: string }> {
+  const args = [
+    'issue', 'edit', String(issueNumber),
+    '--repo', repoSlug,
+    '--title', title,
+    '--body', body,
+    '--json', 'number,url',
+  ];
+
+  const res = await execFileNoThrow('gh', args, { env });
+
+  if (!res.success) {
+    const status = parseHttpStatus(res.stderr);
+    throw new SyncError('github', status, res.stderr, `Update failed: ${res.stderr}`);
+  }
+
+  return JSON.parse(res.stdout);
+}
+
+function getEnv(token?: string): NodeJS.ProcessEnv {
+  if (token) {
+    return { ...process.env, GH_TOKEN: token };
+  }
+  return process.env;
+}

package/plugins/specweave/lib/integrations/github/github-rate-limiter.js

@@ -0,0 +1,96 @@
+import { execFileNoThrow } from "../../../../../src/utils/execFileNoThrow.js";
+const CALLS_PER_USER_STORY = 3;
+const CALLS_PER_SPEC_OVERHEAD = 2;
+class GitHubRateLimiter {
+  constructor(token) {
+    this.totalUsed = 0;
+    this.knownLimit = 0;
+    this.token = token;
+  }
+  /**
+   * Query current GitHub API rate limit via `gh api rate_limit`.
+   */
+  async checkRateLimit() {
+    const env = this.getEnv();
+    const result = await execFileNoThrow("gh", ["api", "rate_limit"], { env });
+    if (!result.success) {
+      throw new Error(`gh CLI failed: ${result.stderr || result.error?.message || "unknown error"}`);
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(result.stdout);
+    } catch {
+      throw new Error(`Failed to parse rate limit response: ${result.stdout.slice(0, 100)}`);
+    }
+    const core = parsed?.resources?.core;
+    if (!core || core.remaining === void 0 || core.limit === void 0 || core.reset === void 0) {
+      throw new Error("Rate limit response missing expected fields (resources.core)");
+    }
+    this.knownLimit = core.limit;
+    const percentUsed = core.limit > 0 ? (core.limit - core.remaining) / core.limit * 100 : 0;
+    return {
+      remaining: core.remaining,
+      limit: core.limit,
+      resetAt: new Date(core.reset * 1e3),
+      percentUsed
+    };
+  }
+  /**
+   * Estimate how many API calls a sync operation will require.
+   */
+  estimateApiCalls(specCount, userStoryCount) {
+    if (specCount === 0 && userStoryCount === 0) {
+      return 0;
+    }
+    return specCount * CALLS_PER_SPEC_OVERHEAD + userStoryCount * CALLS_PER_USER_STORY;
+  }
+  /**
+   * Check whether a sync operation can proceed given the current rate limit.
+   */
+  async canProceed(estimatedCalls) {
+    const status = await this.checkRateLimit();
+    if (estimatedCalls > status.remaining) {
+      const waitMs = Math.max(0, status.resetAt.getTime() - Date.now());
+      return {
+        allowed: false,
+        waitMs,
+        reason: `Rate limit: need ${estimatedCalls} calls but only ${status.remaining}/${status.limit} remaining. Resets in ${Math.ceil(waitMs / 1e3)}s`
+      };
+    }
+    if (status.percentUsed > 90) {
+      const waitMs = Math.max(0, status.resetAt.getTime() - Date.now());
+      return {
+        allowed: false,
+        waitMs,
+        reason: `Rate limit at ${status.percentUsed.toFixed(0)}% \u2014 too high to proceed safely`
+      };
+    }
+    return { allowed: true };
+  }
+  /**
+   * Record API calls made during a sync operation.
+   */
+  recordUsage(calls) {
+    if (calls < 0) {
+      throw new Error("Cannot record negative usage");
+    }
+    this.totalUsed += calls;
+  }
+  /**
+   * Get the percentage of the known limit used by this limiter instance.
+   */
+  getUsagePercent() {
+    if (this.knownLimit === 0) return 0;
+    const pct = this.totalUsed / this.knownLimit * 100;
+    return Math.min(pct, 100);
+  }
+  getEnv() {
+    if (this.token) {
+      return { ...process.env, GH_TOKEN: this.token };
+    }
+    return process.env;
+  }
+}
+export {
+  GitHubRateLimiter
+};

package/plugins/specweave/lib/integrations/github/github-rate-limiter.ts

@@ -0,0 +1,143 @@
+/**
+ * GitHub Rate Limiter
+ *
+ * Shared token-bucket rate limiter for multi-repo GitHub sync.
+ * Queries `gh api rate_limit`, tracks cumulative usage, and gates
+ * sync operations when approaching API limits.
+ *
+ * @module github-rate-limiter
+ */
+
+import { execFileNoThrow } from '../../../../../src/utils/execFileNoThrow.js';
+
+export interface RateLimitStatus {
+  /** Remaining requests in current window */
+  remaining: number;
+  /** Total limit per window */
+  limit: number;
+  /** When the rate limit resets */
+  resetAt: Date;
+  /** Percentage of limit used (0-100) */
+  percentUsed: number;
+}
+
+interface CanProceedResult {
+  allowed: boolean;
+  waitMs?: number;
+  reason?: string;
+}
+
+/** Calls per user story: search + create/update + labels */
+const CALLS_PER_USER_STORY = 3;
+/** Overhead per spec: milestone check, project check */
+const CALLS_PER_SPEC_OVERHEAD = 2;
+
+export class GitHubRateLimiter {
+  private token?: string;
+  private totalUsed = 0;
+  private knownLimit = 0;
+
+  constructor(token?: string) {
+    this.token = token;
+  }
+
+  /**
+   * Query current GitHub API rate limit via `gh api rate_limit`.
+   */
+  async checkRateLimit(): Promise<RateLimitStatus> {
+    const env = this.getEnv();
+    const result = await execFileNoThrow('gh', ['api', 'rate_limit'], { env });
+
+    if (!result.success) {
+      throw new Error(`gh CLI failed: ${result.stderr || result.error?.message || 'unknown error'}`);
+    }
+
+    let parsed: { resources?: { core?: { remaining?: number; limit?: number; reset?: number } } };
+    try {
+      parsed = JSON.parse(result.stdout);
+    } catch {
+      throw new Error(`Failed to parse rate limit response: ${result.stdout.slice(0, 100)}`);
+    }
+
+    const core = parsed?.resources?.core;
+    if (!core || core.remaining === undefined || core.limit === undefined || core.reset === undefined) {
+      throw new Error('Rate limit response missing expected fields (resources.core)');
+    }
+
+    this.knownLimit = core.limit;
+
+    const percentUsed = core.limit > 0
+      ? ((core.limit - core.remaining) / core.limit) * 100
+      : 0;
+
+    return {
+      remaining: core.remaining,
+      limit: core.limit,
+      resetAt: new Date(core.reset * 1000),
+      percentUsed,
+    };
+  }
+
+  /**
+   * Estimate how many API calls a sync operation will require.
+   */
+  estimateApiCalls(specCount: number, userStoryCount: number): number {
+    if (specCount === 0 && userStoryCount === 0) {
+      return 0;
+    }
+    return (specCount * CALLS_PER_SPEC_OVERHEAD) + (userStoryCount * CALLS_PER_USER_STORY);
+  }
+
+  /**
+   * Check whether a sync operation can proceed given the current rate limit.
+   */
+  async canProceed(estimatedCalls: number): Promise<CanProceedResult> {
+    const status = await this.checkRateLimit();
+
+    if (estimatedCalls > status.remaining) {
+      const waitMs = Math.max(0, status.resetAt.getTime() - Date.now());
+      return {
+        allowed: false,
+        waitMs,
+        reason: `Rate limit: need ${estimatedCalls} calls but only ${status.remaining}/${status.limit} remaining. Resets in ${Math.ceil(waitMs / 1000)}s`,
+      };
+    }
+
+    if (status.percentUsed > 90) {
+      const waitMs = Math.max(0, status.resetAt.getTime() - Date.now());
+      return {
+        allowed: false,
+        waitMs,
+        reason: `Rate limit at ${status.percentUsed.toFixed(0)}% — too high to proceed safely`,
+      };
+    }
+
+    return { allowed: true };
+  }
+
+  /**
+   * Record API calls made during a sync operation.
+   */
+  recordUsage(calls: number): void {
+    if (calls < 0) {
+      throw new Error('Cannot record negative usage');
+    }
+    this.totalUsed += calls;
+  }
+
+  /**
+   * Get the percentage of the known limit used by this limiter instance.
+   */
+  getUsagePercent(): number {
+    if (this.knownLimit === 0) return 0;
+    const pct = (this.totalUsed / this.knownLimit) * 100;
+    return Math.min(pct, 100);
+  }
+
+  private getEnv(): NodeJS.ProcessEnv {
+    if (this.token) {
+      return { ...process.env, GH_TOKEN: this.token };
+    }
+    return process.env;
+  }
+}

package/plugins/specweave/lib/integrations/github/github-spec-commit-sync.d.ts

@@ -0,0 +1,37 @@
+/**
+ * GitHub Spec Commit Sync
+ *
+ * Posts commit/PR comments to GitHub issues linked to living docs specs.
+ * This enables traceability from spec user stories to actual code changes.
+ */
+import { GitCommit, GitRepository } from '../../../../../src/utils/git-utils.js';
+import { UserStory } from '../../../../../src/core/specs/spec-task-mapper.js';
+export interface SyncOptions {
+    incrementPath: string;
+    dryRun?: boolean;
+    verbose?: boolean;
+}
+export interface SyncResult {
+    success: boolean;
+    commentsPosted: number;
+    errors: string[];
+    commits: GitCommit[];
+    userStories: UserStory[];
+}
+/**
+ * Sync commits for completed user stories to GitHub issue
+ */
+export declare function syncSpecCommitsToGitHub(options: SyncOptions): Promise<SyncResult>;
+/**
+ * Post batch commit update to GitHub issue (for multiple commits)
+ */
+export declare function postCommitBatchUpdate(incrementPath: string, commits: GitCommit[], issueNumber: number, repo: GitRepository, dryRun?: boolean): Promise<boolean>;
+/**
+ * Check if spec commit sync is enabled in config
+ */
+export declare function isSpecCommitSyncEnabled(projectRoot: string): Promise<boolean>;
+/**
+ * Get GitHub issue number from spec metadata
+ */
+export declare function getGitHubIssueForSpec(specPath: string): Promise<number | null>;
+//# sourceMappingURL=github-spec-commit-sync.d.ts.map

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

@@ -0,0 +1,186 @@
+import { GitHubClientV2 } from "./github-client-v2.js";
+import {
+  getRecentCommits,
+  detectRepository,
+  getCommitUrl,
+  findPRForCommit,
+  getLastSyncCommit,
+  updateLastSyncCommit
+} from "../../../../../src/utils/git-utils.js";
+import {
+  getSpecTaskMapping,
+  getCompletedUserStories
+} from "../../../../../src/core/specs/spec-task-mapper.js";
+import {
+  buildUserStoryComment,
+  buildCommitBatchComment,
+  buildShortComment,
+  generateSmartSummary
+} from "../../../../../src/core/comment-builder.js";
+import path from "path";
+import fs from "fs/promises";
+async function syncSpecCommitsToGitHub(options) {
+  const { incrementPath, dryRun = false, verbose = false } = options;
+  const result = {
+    success: true,
+    commentsPosted: 0,
+    errors: [],
+    commits: [],
+    userStories: []
+  };
+  try {
+    const metadataPath = path.join(incrementPath, "metadata.json");
+    let metadata;
+    try {
+      metadata = JSON.parse(await fs.readFile(metadataPath, "utf-8"));
+    } catch {
+      result.errors.push("No metadata.json found");
+      return result;
+    }
+    const githubIssue = metadata.github?.issue;
+    if (!githubIssue) {
+      if (verbose) {
+        console.log("No GitHub issue linked to increment");
+      }
+      return result;
+    }
+    const repo = await detectRepository("origin", incrementPath);
+    if (!repo || repo.provider !== "github") {
+      result.errors.push("Not a GitHub repository or remote not found");
+      result.success = false;
+      return result;
+    }
+    const mapping = await getSpecTaskMapping(incrementPath);
+    if (!mapping) {
+      if (verbose) {
+        console.log("No spec mapping found for increment");
+      }
+      return result;
+    }
+    const completedUserStories = getCompletedUserStories(mapping);
+    if (completedUserStories.length === 0) {
+      if (verbose) {
+        console.log("No completed user stories");
+      }
+      return result;
+    }
+    result.userStories = completedUserStories;
+    const lastSyncCommit = await getLastSyncCommit(metadataPath);
+    const commits = lastSyncCommit ? await getRecentCommits(void 0, lastSyncCommit, incrementPath) : await getRecentCommits("7.days", void 0, incrementPath);
+    if (commits.length === 0) {
+      if (verbose) {
+        console.log("No new commits since last sync");
+      }
+      return result;
+    }
+    result.commits = commits;
+    for (const commit of commits) {
+      commit.url = getCommitUrl(commit, repo);
+    }
+    const client = GitHubClientV2.fromRepo(repo.owner, repo.repo);
+    for (const userStory of completedUserStories) {
+      try {
+        const relatedTasks = mapping.tasks.filter(
+          (t) => t.userStories.includes(userStory.id)
+        );
+        const pullRequests = [];
+        for (const commit of commits.slice(0, 3)) {
+          const pr = await findPRForCommit(commit.sha, repo.owner, repo.repo);
+          if (pr && !pullRequests.find((p) => p.number === pr.number)) {
+            pullRequests.push(pr);
+          }
+        }
+        const summary = generateSmartSummary(commits, relatedTasks);
+        const commentContent = {
+          userStory,
+          tasks: relatedTasks,
+          commits,
+          pullRequests,
+          summary
+        };
+        const formattedComment = buildUserStoryComment(commentContent, repo);
+        if (verbose) {
+          console.log(`
+Comment for ${userStory.id}:`);
+          console.log(formattedComment.markdown);
+          console.log("\n---\n");
+        }
+        if (!dryRun) {
+          await client.addComment(githubIssue, formattedComment.markdown);
+          result.commentsPosted++;
+        } else {
+          result.commentsPosted++;
+        }
+      } catch (error) {
+        result.errors.push(`Failed to post comment for ${userStory.id}: ${error.message}`);
+      }
+    }
+    if (completedUserStories.length === 0 && commits.length > 0) {
+      try {
+        const summary = `Work in progress: ${commits.length} commit${commits.length > 1 ? "s" : ""}`;
+        const formattedComment = buildShortComment(commits, repo, summary);
+        if (verbose) {
+          console.log(`
+Short update comment:`);
+          console.log(formattedComment.markdown);
+          console.log("\n---\n");
+        }
+        if (!dryRun) {
+          await client.addComment(githubIssue, formattedComment.markdown);
+          result.commentsPosted++;
+        } else {
+          result.commentsPosted++;
+        }
+      } catch (error) {
+        result.errors.push(`Failed to post short update: ${error.message}`);
+      }
+    }
+    if (!dryRun && commits.length > 0) {
+      await updateLastSyncCommit(metadataPath, commits[0].sha);
+    }
+  } catch (error) {
+    result.success = false;
+    result.errors.push(error.message);
+  }
+  return result;
+}
+async function postCommitBatchUpdate(incrementPath, commits, issueNumber, repo, dryRun = false) {
+  try {
+    const client = GitHubClientV2.fromRepo(repo.owner, repo.repo);
+    for (const commit of commits) {
+      commit.url = getCommitUrl(commit, repo);
+    }
+    const formattedComment = buildCommitBatchComment(commits, repo, true);
+    if (!dryRun) {
+      await client.addComment(issueNumber, formattedComment.markdown);
+    }
+    return true;
+  } catch (error) {
+    console.error(`Failed to post batch update: ${error.message}`);
+    return false;
+  }
+}
+async function isSpecCommitSyncEnabled(projectRoot) {
+  try {
+    const configPath = path.join(projectRoot, ".specweave", "config.json");
+    const config = JSON.parse(await fs.readFile(configPath, "utf-8"));
+    return config.sync?.settings?.postCommitComments !== false;
+  } catch {
+    return true;
+  }
+}
+async function getGitHubIssueForSpec(specPath) {
+  try {
+    const content = await fs.readFile(specPath, "utf-8");
+    const match = content.match(/github\.com\/[\w-]+\/[\w-]+\/issues\/(\d+)/);
+    return match ? parseInt(match[1], 10) : null;
+  } catch {
+    return null;
+  }
+}
+export {
+  getGitHubIssueForSpec,
+  isSpecCommitSyncEnabled,
+  postCommitBatchUpdate,
+  syncSpecCommitsToGitHub
+};