specweave 1.0.506 → 1.0.508

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

@@ -1,188 +0,0 @@
-/**
- * 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-github/lib/github-rate-limiter.js

@@ -1,96 +0,0 @@
-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-github/lib/github-rate-limiter.ts

@@ -1,143 +0,0 @@
-/**
- * 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-github/lib/github-spec-commit-sync.d.ts

@@ -1,37 +0,0 @@
-/**
- * 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-github/lib/github-spec-commit-sync.js

@@ -1,186 +0,0 @@
-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
-};