specweave 1.0.235 → 1.0.239

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

@@ -0,0 +1,119 @@
+import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
+import { generateIssueBody } from "./github-issue-body-generator.js";
+async function pushSyncUserStories(userStories, options) {
+  const result = { 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) {
+        const updated = await updateIssue(existing.number, title, body, repoSlug, env);
+        result.updated.push({
+          userStoryId: us.id,
+          issueNumber: updated.number,
+          issueUrl: updated.url
+        });
+      } else {
+        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, repoSlug, env) {
+  const res = await execFileNoThrow("gh", [
+    "issue",
+    "list",
+    "--repo",
+    repoSlug,
+    "--search",
+    `[${usId}] in:title`,
+    "--json",
+    "number,title,node_id",
+    "--limit",
+    "1"
+  ], { env });
+  if (!res.success) {
+    throw new Error(`Search failed: ${res.stderr}`);
+  }
+  const issues = JSON.parse(res.stdout);
+  return issues.length > 0 ? issues[0] : null;
+}
+async function createIssue(title, body, us, repoSlug, env) {
+  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) {
+    throw new Error(`Create failed: ${res.stderr}`);
+  }
+  return JSON.parse(res.stdout);
+}
+async function updateIssue(issueNumber, title, body, repoSlug, env) {
+  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) {
+    throw new Error(`Update failed: ${res.stderr}`);
+  }
+  return JSON.parse(res.stdout);
+}
+function getEnv(token) {
+  if (token) {
+    return { ...process.env, GH_TOKEN: token };
+  }
+  return process.env;
+}
+export {
+  pushSyncUserStories
+};

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

@@ -0,0 +1,174 @@
+/**
+ * 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';
+
+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,
+    '--search', `[${usId}] in:title`,
+    '--json', 'number,title,node_id',
+    '--limit', '1',
+  ], { env });
+
+  if (!res.success) {
+    throw new Error(`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) {
+    throw new Error(`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) {
+    throw new Error(`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

@@ -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-github/lib/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-github/lib/github-spec-frontmatter-updater.js

@@ -0,0 +1,117 @@
+import { readFile, writeFile } from "fs/promises";
+async function updateSpecFrontmatter(specPath, syncResult, options) {
+  const content = await readFile(specPath, "utf-8");
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  let frontmatter = {};
+  let body = content;
+  if (fmMatch) {
+    frontmatter = parseYamlSimple(fmMatch[1]);
+    body = content.slice(fmMatch[0].length);
+  }
+  const externalLinks = frontmatter.externalLinks ?? {};
+  const existingGithub = externalLinks.github ?? {};
+  const existingUserStories = existingGithub.userStories ?? {};
+  const userStories = { ...existingUserStories };
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  for (const item of syncResult.created) {
+    userStories[item.userStoryId] = {
+      issueNumber: item.issueNumber,
+      issueUrl: item.issueUrl,
+      issueNodeId: item.issueNodeId,
+      syncedAt: now
+    };
+  }
+  for (const item of syncResult.updated) {
+    const existing = userStories[item.userStoryId];
+    userStories[item.userStoryId] = {
+      issueNumber: item.issueNumber,
+      issueUrl: item.issueUrl,
+      issueNodeId: existing?.issueNodeId,
+      syncedAt: now
+    };
+  }
+  const syncStatus = syncResult.errors.length > 0 ? "dirty" : "synced";
+  const metadata = {
+    syncStatus,
+    userStories
+  };
+  if (options?.projectV2Id) {
+    metadata.projectV2Id = options.projectV2Id;
+  } else if (existingGithub.projectV2Id) {
+    metadata.projectV2Id = existingGithub.projectV2Id;
+  }
+  if (options?.projectV2Number) {
+    metadata.projectV2Number = options.projectV2Number;
+  } else if (existingGithub.projectV2Number) {
+    metadata.projectV2Number = existingGithub.projectV2Number;
+  }
+  externalLinks.github = metadata;
+  frontmatter.externalLinks = externalLinks;
+  const newFrontmatter = stringifyYaml(frontmatter);
+  const newContent = `---
+${newFrontmatter}
+---${body}`;
+  await writeFile(specPath, newContent, "utf-8");
+  return metadata;
+}
+function parseYamlSimple(yaml) {
+  const result = {};
+  const lines = yaml.split("\n");
+  const stack = [
+    { obj: result, indent: -1 }
+  ];
+  for (const line of lines) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const indent = line.search(/\S/);
+    const trimmed = line.trim();
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = trimmed.slice(0, colonIdx).trim();
+    const rawValue = trimmed.slice(colonIdx + 1).trim();
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+    const parent = stack[stack.length - 1].obj;
+    if (rawValue === "" || rawValue === void 0) {
+      const child = {};
+      parent[key] = child;
+      stack.push({ obj: child, indent });
+    } else {
+      parent[key] = parseYamlValue(rawValue);
+    }
+  }
+  return result;
+}
+function parseYamlValue(raw) {
+  if (raw === "null") return null;
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (/^-?\d+$/.test(raw)) return parseInt(raw, 10);
+  if (/^-?\d+\.\d+$/.test(raw)) return parseFloat(raw);
+  if (raw.startsWith('"') && raw.endsWith('"') || raw.startsWith("'") && raw.endsWith("'")) {
+    return raw.slice(1, -1);
+  }
+  return raw;
+}
+function stringifyYaml(obj, indent = 0) {
+  const prefix = "  ".repeat(indent);
+  const parts = [];
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === null || value === void 0) {
+      parts.push(`${prefix}${key}: null`);
+    } else if (typeof value === "object" && !Array.isArray(value)) {
+      parts.push(`${prefix}${key}:`);
+      parts.push(stringifyYaml(value, indent + 1));
+    } else if (typeof value === "string") {
+      parts.push(`${prefix}${key}: "${value}"`);
+    } else if (typeof value === "boolean" || typeof value === "number") {
+      parts.push(`${prefix}${key}: ${value}`);
+    } else {
+      parts.push(`${prefix}${key}: ${JSON.stringify(value)}`);
+    }
+  }
+  return parts.join("\n");
+}
+export {
+  updateSpecFrontmatter
+};